Errors

The running jobjob_7Hq2 · delivered · document.fr-CA.pdf · $49.00 charged

Every code a call or check can return, with its category, its HTTP status and the operations that return it. A buyer’s or member’s code renders on the brand’s own /docs/errors/<code>.

52 codes a call can answer with, and 31 gates check can fail. Every refusal takes one shape, on all four surfaces: Answers covers it, and next, the call that fixes it when one can.

One refusal

Output

magic values: none

$ curl http://localhost:8787/jobs/job_0000
← 404 · {
  "type": "EMPTY",
  "category": "invalid_request",
  "code": "not_found",
  "reason": "No job job_0000.",
  "param": "id",

Every refusal’s type is its AXP envelope, the word an agent dispatches on: EMPTY for a 404, an id nothing has, and BLOCKED for every other no. Its category is the kind of no, and says whether the same call can ever work.

Every code, by category

Each code renders on the brand’s own site at /docs/errors/<code>, the doc_url its refusal carries, in the brand’s words. A code more than three calls can answer shows their count; Operations names, for each call, every code it can answer.

`invalid_request` codes

Code	HTTP	Operations	Means	Fix
`input_invalid`	422	36 operations	The order doesn't match the Service's input.	Fill the fields next.fill names, then send next.
`not_found`	404	58 operations	Nothing has that id.	Read /.well-known/agents.json for the Services, and use the id an answer returned.
`route_unknown`	404	—	No operation is served at that HTTP method and path.	Read /openapi.json for every route, or /llms.txt for every operation.
`body_invalid`	400	46 operations	The body isn't JSON.	Send a JSON object with content-type: application/json.
`version_unknown`	400	every operation	This brand doesn't serve that Services-Version.	Leave Services-Version out, or send one the answer names.
`policy_invalid`	422	`service.order`, `job.again`, `job.policy`	A policy value is out of bounds; the reason lists each.	Fix the values next.fill names.
`evidence_required`	422	`clock.satisfy`	A clock closes on evidence on the record: a file, or a receipt or file the job already holds.	Send evidence: a file { url, name }, or the id of a receipt (rcp_…) or the sha256 of a file the job holds.
`event_id_required`	422	`event.inbound`	An event that mints a job on a subscription is one occurrence: it needs your id for it.	Send id: your own id for the event, such as the notice number. The same id sent again answers replayed: true and mints nothing more.
`defects_required`	422	`task.send_back`	A send-back names its defects: what is wrong, for the step it returns to.	Send defects, and to: the step it returns to, when it is not the one before.
`memo_required`	422	`task.decline`	A decline carries a reasoned memo, which only the client reads.	Send memo: why you decline. The decline is paid, and never scored.
`evidence_missing`	422	`task.complete`	The step completes on evidence items that are not all present.	Capture each missing item the refusal names, then complete again.

`conflict` codes

Code	HTTP	Operations	Means	Fix
`key_reused`	409	15 operations	That key was already sent with a different body.	Send next: the same call under a fresh key. To get the first answer back, resend it with its original body.
`not_waiting`	409	`job.send_back`, `job.approve`	The job isn't waiting on a person.	Read the job with get_job. Accept or send back a delivered one.
`not_delivered`	409	`job.accept`, `job.send_back`	Only a delivered job can be accepted or sent back.	Wait for delivery with get_job.
`not_cancelable`	409	`job.cancel`	The job is already delivered. Send it back instead.	Send it back with a note, and the AI redoes it.
`nothing_to_redo`	409	`job.send_back`	This job's work came from another Service that already delivered, so there's nothing to redo.	Accept the job as delivered.
`end_not_allowed`	409	`job.end`, `job.approve`, `task.attest`	The job can't end that way now.	Read the reason.
`not_terminal`	409	`job.again`	Only an ended job is ordered again.	Wait for it to end, or cancel.
`period_taken`	409	`service.order`, `job.again`	A job of this Service already holds the subject's period: one live or ended job per period.	Send next: the follow-on the job's end offers, such as an amendment, ordered from that job. A canceled job frees its period.
`evidence_used`	409	`clock.satisfy`	That evidence closed another clock already: evidence closes one clock.	Send what proves this clock itself. next reads the clock the evidence closed.
`clock_closed`	409	4 operations	The clock is closed: it was satisfied, or its owner chose at its date.	Read the clock with GET /clocks/:id: a closed clock takes no more calls. A recurring one brings its next occurrence when it is satisfied, and stays open.
`clock_not_due`	409	`clock.choose`	The owner chooses at the clock's date.	Read the clock with GET /clocks/:id: its rungs and its date. The choice opens at clock.due.
`clock_moved_on`	409	`clock.ack`, `clock.satisfy`, `clock.choose`	The clock is at another occurrence than the due you sent: it moved, or recurred, since you read it.	Send next: the same call, with due set to the date the clock is at now. Read it first if you need to decide again.
`date_passed`	409	`job.approve`, `task.attest`	The step is barred: a hard date on the job passed unsatisfied, and nothing moves it.	Read the clock with GET /clocks/:id: its owner chooses among its lapse options. A charge that waits on a barred step never releases.
`clock_behind`	409	`test_clock.advance`	A test clock only moves forward, and that time is behind it.	Send to: a time after frozen_at, or a span. Sending the time it reads already changes nothing.
`clock_advancing`	409	`test_clock.advance`	The test clock is advancing already: one advance at a time.	Wait for the advance in flight, then read the clock and send yours.
`task_taken`	409	9 operations	Another member holds this Task, or has it offered to them first.	Read your feed for the Tasks offered to you now.
`needs_direction`	409	`task.attest`	A member declined, and only the client's direction moves the job on: another member, or an end.	Hand the client the direct ask in next; nothing else moves it.
`not_contestable`	409	`task.contest`	There is no send-back on this attested work to contest, or it is already contested or ruled.	Read the Task: a contest answers a send-back your attested work received, once.
`job_ended`	409	9 operations	The job has ended, for good.	Order it again with next.
`question_open`	409	`task.message`	A question to the client is out already, and their reply comes through the thread.	Wait for the reply, or post a note: a note expects none.
`ask_expired`	410	`ask.complete`, `ask.reissue`	This ask expired.	Hand over the new link in next.
`ask_voided`	410	`ask.complete`, `ask.reissue`	This link no longer works: used, reissued or voided.	Use the link in next.
`signature_void`	409	`ask.complete`	What was signed changed past its tolerance.	Sign the new version in next.

`authentication` codes

Code	HTTP	Operations	Means	Fix
`key_missing`	401	38 operations	No key: send Authorization: Bearer sk_test_….	Send the key dev printed, as Authorization: Bearer sk_test_….
`key_invalid`	401	38 operations	That key isn't one of this brand's.	Send the key dev printed, as Authorization: Bearer sk_test_….

`blocked` codes

Code	HTTP	Operations	Means	Fix
`needs_a_person`	403	32 operations	A person approves and signs, in the app. A key or a tool never can.	Wait for the job with get_job; it carries on once the person acts.
`merits_not_yours`	403	`job.policy`	Only the client sets the merits.	Ask the client to set it through their own call, POST /jobs/:id/policy, with their key.
`needs_the_owner`	403	`clock.ack`, `clock.satisfy`, `clock.choose`	Only the clock's owner can do this: acknowledge it, satisfy it, or choose at its date.	Hand the clock to its owner: next is where they act on it.
`needs_grant`	403	`job.approve`	A grant this step needs isn't live: not given yet, expired or revoked.	Hand the party the grant link in next; the step runs once they grant it.
`ineligible`	403	5 operations	The member can't take this Task: the answer names the first eligibility predicate they fail, and its cure.	Read predicate and cure. A credential, a region or coverage is cured at /join and by the verifier; availability by setting it on.
`not_cleared`	403	5 operations	The packet opens only to the member who claimed the Task and cleared it.	Claim the Task, then clear it: attest each statement on its sheet.
`not_on_site`	403	`task.arrive`, `task.complete`	The check-in is outside the site radius, or outside the window's early and late marks.	Check in from the site, inside the window. The refusal names the distance and the time.
`reserved`	403	`task.attest`	The rules reserve this act to a credential the person who attested doesn't hold. Nothing was charged.	A person who holds reserved_to attests it, in the region the rule names. The refusal names the act, who it is reserved to and the row it cites.
`act_refused`	403	`service.order`	The rules refuse this act here: it is never performed by this brand. Nothing was charged.	Follow cure.route: the act is performed there, never here. The refusal names the act and the row it cites.
`talk_off`	403	`job.message`, `job.thread`, `task.message`	This Service's jobs have no thread: its talk is off.	Reach the brand another way, or order a Service whose talk is on.
`needs_the_party`	403	6 operations	Only the party can do this, through their own link.	Hand them the link in next.

`guard` codes

Code	HTTP	Operations	Means	Fix
`guard_refused`	422	`job.approve`, `task.attest`	A guard refused the output, and says why.	Fix that value; the step stays open.

`unavailable` codes

Code	HTTP	Operations	Means	Fix
`not_live`	403	`service.order`, `job.again`	This Service takes no orders yet.	Join the waitlist in next.
`region_not_ratified`	403	`service.order`	The rules don't ratify this act in the job's region yet. Nothing was charged.	Join the waitlist in next, and you hear when the region is ratified.
`brand_unverified`	403	`service.order`	A credential the brand itself holds is unverified or stale, so the act it covers waits. Nothing was charged.	Join the waitlist in next, and you hear when the brand's verifier renews it.

`api_error` codes

Code	HTTP	Operations	Means	Fix
`api_error`	500	every operation	Something failed on our side.	Send the same call again with the same Idempotency-Key; quote the request_id if it fails twice.

The fields each code adds

Every refusal carries the one shape. These codes add fields of their own, typed on the code, so e.code === 'ineligible' narrows to its predicate and its cure. Each is typed on its code, then shown as a call answers it. A field marked ? can be left out.

`not_on_site` fields

A check-in or a check-out outside the site's radius, or outside the window's marks.

Field	Type
`distance_m`	`number`
`within_m`	`number`
`window`	`{ from: string; to: string }`

`reserved` fields

A reserved act a person who doesn't hold its credential tried to perform.

Field	Type
`act`	`string`
`reserved_to`	`string`
`rule`	`RuleRef`

`act_refused` fields

An act the rules refuse here, ordered by name or performed by a Service: where it is performed instead.

Field	Type
`act`	`string`
`rule`	`RuleRef`
`cure`	`{ route: string \| null }`

captured/legal-refused.txt · 403 · magic values: none

→ POST /matters {"service":"litigate","max_usd":500,"key":"sue-initech"}

`ineligible` fields

A member who can't take a Task: the first predicate they fail, what it needs, what they hold, the cure in words, and in next the call that cures it (none for conflict or separation, by design).

Field	Type
`predicate`	`Predicate`
`needs`	`string`
`holds`	`string`
`cure`	`string`

captured/people-refusals.txt · 403 · ineligible · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ POST /reviews/tsk_7Hq2/claim {}   # as mbr_out_of_region

`region_not_ratified` fields

A reserved act outside the regions its row is ratified in.

Field	Type
`act`	`string`
`region`	`string \| null`
`regions`	`readonly string[]`
`rule`	`RuleRef`

captured/legal-region.txt · 403 · magic values: none

→ POST /matters {"service":"contract-review","contract":{"url":"data:text/plain,A%20lease.","name":"lease.pdf"},"client":{"name":"Ada Lovelace","email":"ada@example.com"},"client_region":"US-FL","max_usd":99,"key":"lease-fl"}

`brand_unverified` fields

An act under a credential the brand holds while that credential is unverified or stale.

Field	Type
`act`	`string`
`credentials`	`readonly string[]`
`rule`	`RuleRef`

captured/brand-credential.txt · 403 · magic values: metadata.sandbox.brand = verified, metadata.sandbox.brand = stale

→ POST /jobs {"service":"extension","year":2025,"max_usd":25,"key":"stale","metadata":{"sandbox":{"brand":"stale"}}}

`needs_the_party` fields

Only the party can do it: their own link, or their own signed-in session, in next.

Field	Type
`party?`	`string`

captured/hand-to-person.txt · 403 · magic values: none

→ POST /asks/ask_7Hq2 {"items":{"terms":{"answer":"Lessee"}}}   # its key, without the link

`period_taken` fields

The subject's period is held: the subject, the period, the job that holds it, and the follow-on Services its end offers.

Field	Type
`subject`	`string`
`period`	`string`
`job`	`string`
`follow`	`readonly string[]`

captured/period-tabs.txt · 409 · magic values: none

$ curl -X POST http://localhost:8787/glossary -H 'content-type: application/json' -d '{"account":"acme","year":"2025","terms":["Premises"],"max_usd":19,"key":"glossary-2025-again"}'   # a second order for 2025

`rule` fields

A refusal the rules bring names its row in rule, a RuleRef, printed as rules <version> · <row>. Objects shows it inside a body.

Field	Type
`version`	`string`
`at`	`string`
`position`	`string`
`cite?`	`readonly string[]`

A member’s and a client’s codes, as served

The rest of the codes a member’s session or a client’s link meets, each as a real run answered it: its frame is titled with its code, and its body is whole on "Show all".

captured/people-refusals.txt · 403 · not_cleared · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ GET /reviews/tsk_7Hq2/packet   # as mbr_eligible, before clearing it

captured/people-refusals.txt · 409 · task_taken · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ POST /reviews/tsk_7Hq2/claim {}   # as mbr_lapsed_coverage, once mbr_eligible holds it

captured/people-refusals.txt · 422 · memo_required · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ POST /reviews/tsk_7Hq2/decline {}   # as mbr_eligible: a decline with no memo

captured/people-refusals.txt · 422 · defects_required · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ POST /reviews/tsk_7Hq2/send_back {}   # as mbr_eligible: a send-back with no defects

captured/people-refusals.txt · 409 · needs_direction · magic values: member = mbr_out_of_region, member = mbr_lapsed_coverage, member = mbr_eligible

→ POST /matters/job_7Hq2/cancel   # the buyer, once a member declined

check’s gates

A failing gate exits 1 and prints its code in check --json. All 31, each one's meaning, its fix and its failing file, are on check’s gates.

The CLI’s own codes

Before any brand answers, npx services.dev can fail on its own. With --json, or SERVICES_DEV_JSON=1, each prints the same shape with one of these codes, its doc_url this page's anchor. The exit code is the code's, so an agent branches on it without reading the words.

Code	Category	Exit	Means
`usage`	`invalid_request`	2	The command is missing something it needs.
`unknown_command`	`invalid_request`	2	No command by that name.
`not_running`	`api_error`	10	Nothing is running at that URL.
`not_a_brand`	`invalid_request`	2	This folder has no Services, or one fails to load.

A refusal from a brand exits by its category: invalid_request 3, authentication 4, blocked 5, unavailable 7, conflict 6, guard 6, rate_limited 10, api_error 10. A failing check exits 1, and usage 2. The CLI lists every command.