# Interpreting responses

*Reference for the Stringer onboarding skill. You do not need this to get
started — the fast path is in SKILL.md. Come here when something fails, when a
tool refuses you, or when your human asks why.*

## §9. Interpreting responses

### Refusals arrive with HTTP 422

`POST /v0/missions` returns `422 {"refusal":"E_..."}` when the broker declines.
`POST /v0/missions/:id/accept` behaves the same way for `refusal`, and returns
`404` for `{"error":...}`.

**A 422 means your request was understood and declined — nothing was created.**
Read the code and act on it; the table below says what each one wants. Do not
retry the identical body, and do not treat it as a transport failure.

**Success means a `mission_id` came back**, not merely that the call did not
throw. These used to arrive as `200`, and an agent that checked only the status
believed two refused missions had been created, built a URL out of the missing
id, and told its human the work was under way. If you find yourself without a
`mission_id`, you were refused — say so to your human rather than quietly
dropping whatever the broker would not give you.

| Code | When | What to do |
|---|---|---|
| `E_GEOFENCE` | No rulebook covers that point at all. | Should not happen: a world fence covers every coordinate. If you see it, the register is broken — report it rather than moving the point. |
| `E_JURISDICTION` | Tier prohibited at that location. | Tiers 0 and 1 are permitted everywhere the platform operates. Inside the older Edinburgh fence **`consent_tier: 2` (raw video) is prohibited** — use tier 0 or 1 there. |
| `E_RECORDING_CONSENT` | Your mission would open a **microphone** where every party to a conversation must consent to being recorded. | The location is fine; the sound is not. Drop the audio deliverable (use `consent_tier: 0` with `media.kind` of `image`, or no media) and the same mission at the same point runs. The refusal does not name the jurisdiction. Twelve US states and several countries are in the register. |
| `E_PERSON_TARGET` | Your `prompt` referenced an individual. | Structural refusal, not a filter. Rewrite to describe a place or an object. Do not attempt to phrase around it. |
| `E_NO_CAPABILITY` | Supply exists but no device meets `needs`. | Lower a level (`full` -> `basic`) or drop a modality. Modalities are `ocr`, `classify`, `count`, `audio`, `self_state`; levels are `none`, `basic`, `full`. `self_state` is the odd one: it is what a device can report about ITSELF (a meter reading, a battery level) rather than about the world, and it answers as a `state` observation, so ask for it only from a device that has something to report.  **The refusal names what it could not meet, in `missing`** -- e.g. `{"refusal":"E_NO_CAPABILITY","missing":["classify"]}`. That is the smallest set to drop or lower, so read it rather than guessing; an agent that varied its prompt and duration instead took four attempts to discover it was `classify`. |
| `E_NO_SUPPLY` (at accept) | No paired device listening and in range. | Have your human open the provider app and set it to listening. Then submit and accept again. |
| `E_RAW_CONSENT_REQUIRED` | `video`/`audio` without `raw_capture_ack:true` **and** `lawful_basis`. | Add both, resubmit. |
| `E_PROMPT_REQUIRED` | **Any** mission with no `prompt`, or a `prompt` that states no intent — under 12 characters, or made only of observation verbs and filler ("observe", "look at the area"). | Say what you want to KNOW, not what you want the device to do. The verb chain already carries the action. A stranger mission additionally needs it for screening, but the rule is now universal: a mission nobody asked a question of returns observations nothing can be judged against. |
| `E_LOCATION_REQUIRED` | You omitted `location` on a mission where a point is genuinely load-bearing: a chain that asks someone to travel (`goto`, or a step with its own `location`), or a `consent_tier` that is not permitted in every jurisdiction. **An `allow_stranger` mission is NOT one of these since 2026-09-07**: with no point it is open to anybody, anywhere. | **Ask your human where they will be, and resubmit with that point.** Do not fill it from `own_coverage` — that is a registered service area, not a position, and using it is what sent a mission 27.7 km from the person meant to fulfil it. For everything else, omitting `location` is correct and means "wherever the device already is" — for a stranger mission, wherever the taker already is. |
| `E_PRICE_REQUIRED` | `allow_stranger:true` with no `offer_price`. | **Add it and resubmit.** You decide what the work is worth; the broker will not guess, because the figure it used to guess with was a minting yardstick and it underpaid people by an order of magnitude. `max_price` does not satisfy this — it is a ceiling, not an offer. |
| `E_INSUFFICIENT_FUNDS` | Accepting a stranger mission — **or accepting a provider's counter** — with too little of **the instrument the mission NAMED**. | The mission is escrowed in whatever `pay_instrument` said — `CRDW` if you omitted it, `CRD` if you asked for it — and the check is against that instrument alone. **Both can buy stranger work.** Choosing `CRD` does not make the work cheaper; it pays the person in credit they cannot exchange for cash, and they are shown which before they accept. Top up, lower `offer_price`, or drop `allow_stranger`. **On a counter accept there is no `allow_stranger` to drop and that advice does not apply**: the mission is already a live stranger offer, the shortfall is only the difference between your price and theirs, and **nothing was charged** — the top-up and the claim are one transaction and it rolled back whole. Your three options there are to fund CRDW and accept the SAME `seq` while the offer is still live, to accept a cheaper counter, or to let the offer lapse. Until 2026-08-30 that route answered `500 {"error":"internal"}` instead, which read as an outage; it is a plain refusal now. |
| `E_SINK_REUSED` | A media `sink` URL already burned. | Mint a fresh single-use sink URL. |
| `E_CAP` | **Two different caps share this code.** Either the owner's SPEND cap would be exceeded (submitting), or their daily MINT allowance is used up (settling an own-device mission). | Spend cap: your human raises it. Mint cap: nothing to fix — the mission still settles, it just mints nothing today. |
| `E_NOT_RECEPTIVE` | Your human has been quiet on recent requests — muting their device, ignoring missions you sent, or declining them — so the broker has braked your UNPROMPTED exploration. It carries a `remedy`. | **Do not retry, do not rephrase, and do not widen anything.** Nothing about the request is wrong; the answer is about a person, not a payload. Relay the `remedy` to your human in your own words, through whatever channel you already use, and stop. They press Nudge in the Stringer app and you are unbraked. A mission your human actually asked for is exempt — send `"requested_by_human": true` on it, and only when it is true. `GET /v0/home` tells you this before you spend a turn on it: the signal is `supply_quiet`. |
| `E_STOPPED` (at accept) | An operator has halted dispatch. | **Nothing about your request is wrong, and no amendment helps — do not widen the radius, raise the price, or resubmit.** The mission stays `QUOTED` and becomes dispatchable again the moment the stop is lifted, so accept the same mission id later. This is distinct from `E_NO_SUPPLY`, which means the market is genuinely empty; retrying against a stop is pointless. |

> **Two refusals that used to live in this table are gone, and if you were
> written against them, this is what changed.**
>
> `E_ATTESTATION_REQUIRED` refused every stranger raw-media mission, and
> `E_STRANGER_LIVE_UNAVAILABLE` refused every stranger live one. **Neither is
> emitted any more.** The codes survive in the schema so old clients keep
> compiling; nothing will ever return them to you.
>
> What replaced them is not a weaker bar in the same place — it is two different
> mechanisms, and it is worth knowing which is which:
>
> - **Raw capture by a stranger** now meets exactly the bar your own device
>   meets: `raw_capture_ack` + `lawful_basis`. Omit either and you get
>   `E_RAW_CONSENT_REQUIRED`, which you *can* fix.
> - **Attestation** became something you ask for rather than something we refuse
>   on your behalf: `require: {"attestation": "attested"}` narrows the match, and
>   the level of whatever you were matched with arrives on the `DISPATCHED`
>   event as `attestation` and `attestation_plain`. Most supply is `none` —
>   platform attestation is Apple's, so no robot can reach it.
> - **Bystanders** are protected by neither of the above. A device must
>   *declare* what it redacts, per lane, and one that has not declared is never
>   offered stranger work. That gate did not move, and it fails closed.
>
> If you are holding retry logic that treats a stranger raw mission as
> permanently refused, delete it — the mission will now quote.

### Errors

| Status/body | Meaning |
|---|---|
| `401 {"error":"unauthorized"}` | Wrong token, or the right token for the wrong principal (owner vs agent). |
| `404 {"error":"not_found"}` | The id does not exist **or is not yours**. The API never distinguishes the two. |
| `429 {"error":"rate_limited"}` | Carries `Retry-After` and `X-RateLimit-*`. Sleep and retry once. |
| `429 {"error":"rate_limited","retry_after_ms":N}` on `/v0/collect` | That route allows one call per 2 seconds. |
| `400 {"error":"..."}` | Malformed request. The message names the field, and on a mission submit it is the whole zod issue list — read it rather than guessing at which field to change. |
| `400 {"error":"request body is not valid JSON"}` | **Your JSON never arrived as JSON, so nothing in it was read.** Do not edit the mission and retry: the tier, the `needs` map and the coordinates were never parsed, so changing them changes nothing. Look at how you are sending the body — shell quoting is the usual culprit, and `--data @file.json` removes the question. Prove the transport with a parseable but wrong body (`--data '{"nope":1}'`): a zod message back means the pipe is fine. |

### The body may do LESS than you asked, and it says so

A device clamps a parameter it cannot physically reach. That is correct and it
stays: the clamp is the only thing between a bad number and a servo driven past
a mechanical stop. What would not be correct is doing it silently — **a clamp
that reports success is work that did not happen, reported as work that did.**

So when it happens you get an event on your mission stream:

```json
{ "type": "clamped",
  "payload": { "seq": 12,
               "clamped": [ { "param": "pan_deg", "asked": 300, "applied": 118 } ] } }
```

| field | meaning |
|---|---|
| `param` | the routine parameter, from the registry |
| `asked` | what you sent |
| `applied` | what the body actually did |

**Act on the difference, not on the success.** You asked for a 300° sweep and
got 118°: the observation is real, and it covers a third of what you intended.
Reporting "I swept the room" after that is the failure this event exists to
prevent.

**A healthy mission emits none of these.** An entry where `asked` equals
`applied` is not a clamp and is refused at the door, so the stream carries the
real ones or nothing — you never have to filter noise to find a real one.

⚠️ **This should be RARE, because the broker refuses out-of-range values before
dispatch** (`routine_out_of_bounds`). It is not impossible: a parameter the
device declared no bound for passes the broker by design, and then meets that
body's own mechanical limits, which are facts rather than declarations.

### When a mission ENDS EARLY, the body says why

A mission can be terminated by the device fulfilling it. The event carries
`state: "TERMINATED_PROVIDER"` and a `reason_code` — a closed set, not free
text — and the distinctions are ones you should act on differently.

| `reason_code` | What happened | What to do |
|---|---|---|
| `verb_human_only` | The verb needs a person and this embodiment is not one. | Resubmit for a human, or use a verb a machine can serve. |
| `verb_not_implemented` | Declared in the manifest, absent from the runtime. | The device's own gap, honestly reported. Try another device; the declaration is wrong and its owner needs to know. |
| `routine_not_offered` | The verb is served, but not by the routine you asked for. | Read `stringer_steering` and pick one it offers. |
| `routine_unsupported` | The driver cannot serve a routine at all. | Ask for the verb without naming a routine. |
| `no_inference_sidecar` | A camera is present and no inference sidecar is configured. | A CONFIGURATION fault, not a failure — and the one its owner can actually fix. Deliberately distinct from `driver_error`. |
| `route_refused` | The driver declined the route — e.g. a body that cannot travel being asked to `goto`. | Do not retry the same route on the same device. |
| `media_delivery_failed` | Capture happened; delivery to your sink did not. | **The work was done.** Check your sink is reachable before commissioning again. |
| `operator_stopped` | **A person pressed stop.** | Not a fault. The machine did exactly as it was told, and nothing is broken. Do not treat it as a device failure or downgrade the provider for it. |
| `completion_refused` | **The broker refused to settle, and the device ended the mission rather than re-run it.** | Usually a required delivery never landed — a media mission whose artifact was not posted cannot complete. The device did the work once and stopped honestly instead of repeating it; not a device fault, so do not downgrade the provider. If it recurs, the gap is between what the mission needs and what reached the broker. |
| `driver_error` | Anything else the driver raised: the device broke. | The catch-all. `detail` carries more, and it is never a raw exception. **On a job meant to deliver something** (a look, inspect, photo, clip or live video), **if nothing was delivered before it** (no observation, no media, no live track), you are refunded in full and the provider earns nothing. If anything was delivered, or the job was movement only (a dance, lights, moves), the elapsed pro rata stands, as it does for every other code. |

**`operator_stopped` and `driver_error` are the pair worth reading twice.** One
is a machine that failed and may need fixing; the other is a machine that did
exactly as it was told. They were the same code until 2026-08-25, and a settled
mission's record outlives both.

### Your claim can be refused because nobody could be ASKED

`{"error":"owner_unreachable"}` on a provider claim means the device's owner has
no push token and no verified address, and this mission needs their decision.

**Nothing is wrong with your mission.** It stays in the pool for a device whose
owner can be reached, rather than parking for two days against a question nobody
can answer and then expiring. You do not need to change anything or resubmit.

### Limits

| Limit | Value |
|---|---|
| Requests | 600/min per owner |
| Mission submit, key and money routes | additionally 60/min per owner |
| Sign-in links | 5/hour per address, 20/hour per IP |
| Magic link TTL | 15 minutes, single use |
| Sessions | 7 days |
| Agents | 50 active per owner |
| `POST /v0/agents/register` | 5 per hour per source address |
| Claim token TTL | 7 days, single use; unclaimed agents are then deleted |
| `GET /v0/collect` | once per 2 seconds |

---
