Error codes

When a call fails, Nexus tells you why in a stable code rather than a message you have to parse. The daemon speaks JSON-RPC numbers. The gateway translates them into HTTP statuses and string codes.

Daemon codes

The -32700 to -32600 range follows JSON-RPC. The -32001 to -32099 range is Nexus’s own.

Code	Name	Meaning
`-32700`	`PARSE_ERROR`	Invalid JSON was received
`-32600`	`INVALID_REQUEST`	The JSON is not a valid request object
`-32601`	`METHOD_NOT_FOUND`	The method does not exist
`-32602`	`INVALID_PARAMS`	The parameters did not match the method’s type
`-32603`	`INTERNAL_ERROR`	Internal server error
`-32001`	`UNAUTHORIZED`	The caller is not authorized for this method, for example a non-admin calling an admin method
`-32002`	`DUPLICATE_NAME`	An agent, thread, topic, or project name is already bound
`-32003`	`NOT_FOUND`	The named agent, thread, topic, or message does not exist
`-32004`	`PROJECT_SCOPE_VIOLATION`	The request reached outside the caller’s project scope
`-32005`	`PAUSED`	The target session is paused, so its message path is closed
`-32006`	`ACTIVE_TURN_REQUIRED`	The active-turn operation raced with completion, or no turn is running
`-32007`	`HOOK_REJECTED`	A blocking message hook rejected the send before it was accepted
`-32008`	`HOOK_GATEWAY_UNAVAILABLE`	Hook evaluation is required but no gateway hook provider is available
`-32009`	`DELIVERY_TIMING_UNSUPPORTED`	The target harness cannot honor the requested delivery timing
`-32010`	`COMMAND_QUEUE_FULL`	The session’s durable prompt queue is at capacity
`-32011`	`DELIVERY_UNCERTAIN`	Native delivery may already have happened

-32008 usually means hook_gateway_mode is set to required while the gateway is down or reconnecting. See Configuration.

HTTP codes

Over REST you never see the negative integers. Every failure is:

{ "error": { "code": "forbidden", "message": "requires admin tier" } }

Status	`code`
`400`	`bad_request`
`401`	`unauthorized`
`403`	`forbidden`
`404`	`not_found`
`409`	`conflict`
`422`	`unprocessable`
`500`	`internal_error`
other `5xx`	`server_error`
other `4xx`	`client_error`

A path that exists but was called with the wrong method returns 405, not 404.

How daemon codes become statuses

When a REST call reaches the daemon and the daemon fails, the gateway maps the number:

Daemon code	HTTP status
`-32700`, `-32600`, `-32602`	`400`
`-32601`	`404`
`-32603`	`500`
`-32001`	`401`
`-32002`	`403`
`-32004`	`404`
anything else	`502`

A 502 therefore means the daemon reported a failure the gateway does not have a status for — the rest of the daemon table above reaches you that way.

REST API for the routes these codes come from
Debugging for working out which part failed

Error codes

Daemon codes

HTTP codes

How daemon codes become statuses

Next