Errors reference

Every non-2xx response uses one envelope. The code is stable; the message is for humans.

Envelope

json

{
  "error": {
    "code": "insufficient_balance",
    "message": "Add funds to continue making requests.",
    "request_id": "…",
    "retryable": false,
    "billing_state": "none",
    "upstream_status": 402,
    "details": { }
  }
}

retryable says whether the same request can be retried unchanged (with the same Idempotency-Key). billing_state tells you whether anything was reserved or charged before the failure — check it before assuming a failed call was free.

Codes

HTTP	Code	Meaning
400	`invalid_input`	The input did not match the tool’s input schema. details lists the fields.
400	`invalid_json`	The body is not valid JSON.
400	`missing_idempotency_key`	Billable calls require an Idempotency-Key header.
401	`invalid_api_key`	The key does not exist or the secret does not match.
401	`session_required`	Dashboard route called without a valid session cookie.
401	`unauthorized`	No credentials or an unrecognised credential type.
402	`insufficient_balance`	Add funds to continue making requests. Nothing was reserved.
402	`spend_limit_exceeded`	A workspace, project or key limit would be exceeded.
403	`csrf_rejected`	Origin or X-Requested-With check failed.
403	`forbidden`	The principal exists but may not perform this action.
403	`insufficient_scope`	The key lacks the scope this route needs.
403	`key_expired`	The key passed its expiry.
403	`key_revoked`	The key was revoked.
403	`sudo_required`	Admin action needs a recent wallet re-signature.
404	`not_found`	Resource does not exist in this workspace.
404	`tool_not_found`	Unknown tool key.
409	`idempotency_conflict`	Same Idempotency-Key with a different body.
409	`idempotency_in_progress`	The first attempt with this key is still running; retry shortly.
409	`quote_expired`	Request a new quote.
409	`quote_mismatch`	Input differs from the quoted input.
409	`state_conflict`	The resource is not in a state that allows this action (e.g. cancelling a finished job).
413	`payload_too_large`	Body exceeds the size limit.
422	`ceiling_too_low`	Your max_charge_usd is below the tool’s minimum charge.
422	`tool_unavailable`	This API is not available yet (not activated, paused, or unconfigured).
422	`unsupported`	The operation is not supported by this tool or adapter.
422	`unsupported_batch`	JSON-RPC batch arrays are rejected.
422	`unsupported_rpc_method`	The JSON-RPC method is not on the allow-list.
422	`upstream_validation_error`	The supplier rejected the input.
429	`rate_limited`	Slow down; see Retry-After.
500	`internal`	Unexpected error; quote the request_id to support.
502	`upstream_error`	The supplier returned an error. billing_state tells you whether anything was charged.
503	`supplier_unavailable`	The supplier is down or paused by a circuit breaker.
503	`supplier_unconfigured`	The supplier is not configured in this deployment.
504	`upstream_timeout`	The supplier did not answer in time; the request is reconciling.