Error Codes

Every failure the plane reports, keyed on its stable slug, with the status it carries and whether sending the call again helps.

Published 19 September 2026

On this page (10)

The error object
Bad request
Refused
Not found
Conflict
Too much for one answer
Slow down
Try again
Errors from the endpoint itself
Malformed Cypher

A failed operation keeps the envelope. ok is false, status carries the status, and error carries the reason.

The error object

text

{
  "op": "policy",
  "ok": false,
  "status": 403,
  "error": {"code": "FORBIDDEN_SCOPE", "message": "<what was missing>", "retryable": false},
  "retry_after": null
}

error is either a string or an object with code, message and retryable. Branch on code. Never branch on message, which is written for a person and changes. On the statuses that carry it, retry_after gives the number of seconds to wait.

Bad request

Code	Status	Condition	What to do
`UNKNOWN_OP`	400	`op` is not an operation the plane accepts.	Check the spelling against Operations.
`BAD_ARGS`	400	An argument is missing, or a value is outside what the argument accepts.	Read the operation's page for the argument shape.
`DOMAIN_NOT_REGISTRABLE`	400	The name in a `domain` call cannot be attached as given.	See Manage a domain.

Refused

Code	Status	Condition	What to do
`FORBIDDEN_SCOPE`	403	The key does not carry the scope the operation needs.	Check the table in Keys and scopes.
`ANONYMOUS_WRITE`	403	A write arrived with no key.	Send `X-API-Key`.
`DEVICE_RESOLVE_ONLY`	403	The credential belongs to a resolve-only device, which cannot change anything.	Use an account key.
`AGENT_REVOKED`	403	The identity named has been cut.	Mint a fresh one with `register`.
`AGENT_EXPIRED`	403	The identity is no longer in service.	Mint a fresh one.
`RESERVED_NAME`, `OFFENSIVE_NAME`, `PREMIUM_NAME`	403	The label is not available under the naming rules.	Pick another label.

Not found

Code	Status	Condition	What to do
`NOT_FOUND`	404	No such identity, address or name under this account.	Read the roster with `list`.

Conflict

Code	Status	Condition	What to do
`REGISTER_IN_PROGRESS`	409	A register for this account is already running.	Wait for it, then read `list`.
`WG_KEY_IN_USE`	409	The WireGuard public key is bound to another identity.	Generate a new pair.
`DOMAIN_TAKEN`, `DOMAIN_IN_BAILIWICK`, `DOMAIN_OVERLAPS_ANOTHER_ACCOUNT`, `DOMAIN_UNDER_HELD_APEX`	409	The name, or a name above it, is held elsewhere or on hold.	Pick a name you hold outright.

Too much for one answer

Code	Status	Condition	What to do
`RESULT_TOO_LARGE`	413	The answer does not fit in one response.	Narrow the window, lower `limit`, or read by `kind`.

Slow down

Code	Status	Condition	What to do
`AGENT_LIMIT`, `IDENTITY_LIMIT`, `TENANT_LIMIT`	`429`	The account's allowance is used up.	Sign in to see the account, or ask Whisper to widen it.
`DOMAIN_LIMIT`, `BYOD_CAPACITY`	`429`	The account cannot take another name right now.	Ask Whisper.
`ACTION_LIMIT`	`429`	Too many actions in flight.	Wait for `retry_after` seconds, then send it again.

Try again

Code	Status	Condition
`STORE_UNAVAILABLE`	503	The store behind the plane did not answer.
`PUBLISH_FAILED`	503	The change did not reach DNS.
`BACKEND_BUSY`, `READ_BUSY`	503	The plane could not take the call right now.
`PRIMARY_UNREACHABLE`	503	The authoritative side did not answer.
`GRAPH_BUSY`	503	The graph could not answer in time.

Treat any 503 as worth sending again, and honour retry_after. On a write, read the state back with list or agent before retrying, so you do not make a second allocation.

Errors from the endpoint itself

These come from the request rather than the operation, so there is no op row to read.

Code	Status	Condition	What to do
`no_query`	400	The body carried no statement.	Send a `query` field, or a `q` form field.
`bad_request`	400	The body could not be read.	Check the JSON.
`unknown_op`	400	The statement named an operation the endpoint does not serve.	See Operations.
`read_only`	400	A raw Cypher statement carried a write clause.	Send reads only. Changes go through `whisper.agents`.
`rate_limited`	`429`	Requests arrived faster than the endpoint took them.	Wait for the interval the response gives, then send it again.
`graph_unavailable`	502	A forwarded graph read could not be served.	Retry.
(no code)	504	A forwarded graph read did not come back.	Narrow the statement, then retry.

Malformed Cypher

A statement the parser cannot read never reaches an operation, so it does not come back in this envelope. It comes back as a problem document instead, described in Errors.

Error Codes Documentation