Errors

Errors on /v1 keep OpenAI's shape, so OpenAI SDKs raise their usual errors:

CodeJSON

Branch on error.code. Some codes add fields inside error: accepts (how to pay) on a payable 402, spend_cap_wei on spend_cap_exceeded. A 429 carries a retry-after header. The OpenAI SDKs have no 402 class: a 402 arrives as a plain API error with status 402. OpenAI SDKs retry 429 and 5xx by themselves, up to their retry count. A retry is a new call: on a call paid per call, it signs and pays a new payment.

By code

Status	`code`	Means	What to do
`400`	`null`	The request is invalid: a missing field, an unsupported role or content type, or the last message is not the user's.	Fix the request; `message` says what is wrong.
`400`	`context_length_exceeded`	The system messages and the last turn alone don't fit one job (about 124 KiB once encrypted).	Shorten them. Older turns are dropped by themselves: see Limits.
`400`	`invalid_payload`, `invalid_x402_version`, `invalid_network`, `invalid_payment_requirements`	A `PAYMENT-SIGNATURE` is malformed, or its `accepted` is not the current entry (the fee changed).	Rebuild it from the answer's `PAYMENT-REQUIRED`.
`400`	`unsupported_scheme`	This server takes no per-call payments.	Send the call without the header, with an API key.
`401`	`invalid_api_key`	The key is missing, unknown or revoked; or a call with no key went to a server that takes no per-call payments.	Send a valid key, or no `Authorization` header at all on a call paid per call.
`402`	`delegate_not_authorized`	The wallet behind the key has not authorized the API's signer.	Send the transaction in `accepts`: see Payment.
`402`	`insufficient_balance`	The prepaid balance cannot cover the job.	Send the `accepts` transaction again to top up.
`402`	`allowance_exhausted`	The API has spent everything the wallet allowed it.	Send it again: it adds balance and allowance.
`402`	`spend_cap_exceeded`	The key reached its lifetime cap (`error.spend_cap_wei`).	Raise or remove the cap: see API Keys.
`402`	`payment_required`	A call with no API key carried no payment.	Pay the `accepts` entry per call, or send an API key.
`402`	`insufficient_funds`	The per-call payer's balance cannot cover the fee.	`deposit()` from the payer's wallet.
`402`	`invalid_prepaid_debit_payload_expired`	The payment's deadline has passed.	Sign a new one.
`402`	`invalid_prepaid_debit_payload_nonce_used`	The payment was already used.	Sign a new one with a fresh nonce.
`402`	`invalid_prepaid_debit_payload_signature`	The signature does not recover to `payer` over this chain and `JobRegistry`.	Sign with the payer's key over the entry's domain.
`402`	`invalid_prepaid_debit_payload_over_cap`	The job's fee is above the payment's `maxAmount`.	Set `maxAmount` to the entry's `amount`.
`402`	`invalid_prepaid_debit_payload_facilitator_mismatch`, `invalid_prepaid_debit_payload_recipient_mismatch`	The payment names another facilitator or `payTo` than the entry.	Copy both from the entry.
`402`	`invalid_prepaid_debit_facilitator_not_authorized`	The server's per-call setup is incomplete.	Pay with an API key meanwhile.
`402`	`invalid_transaction_state`	The chain refused the settlement.	Retry shortly.
`404`	`model_not_found`	No model by that name, or no worker serves it now.	Pick an `id` from `GET /v1/models`, verbatim.
`429`	`rate_limit_exceeded`	Too many calls this minute: per key, per payer, or per address for bad keys.	Wait `retry-after` seconds.
`429`	`concurrency_limit_exceeded`	Too many calls in flight for the key or payer.	Wait `retry-after` seconds, or run fewer at once.
`429`	`session_open_limit_exceeded`	The server opens only so many new sessions a minute.	Wait `retry-after` seconds.
`500`	`null`	The server failed to answer.	Retry with backoff.
`502`	`job_failed`	The worker failed or took too long; the API had already retried once in a new session, if nothing had streamed.	Retry.
`502`	`unexpected_verify_error`, `unexpected_settle_error`	The per-call payment could not be checked or settled.	Send the same `PAYMENT-SIGNATURE` again: a payment that did settle is then refused as used, so it is never charged twice.
`503`	`no_worker_available`	No worker took on a new session within the claim window.	Retry shortly.
`503`	`blob_fee_too_high`	The chain's blob fee is above what the server pays to submit a prompt.	Retry later.
`503`	`not_configured`	Completions are off on this server.	Use another network, or ask its operator.

402 codes for a call with an API key are in Payment: the delegate path; codes for a call paid per call are in Payment: pay-per-call codes.

Key management

The /api routes answer errors as { "error": "<code>", "message": "…" }, not in OpenAI's shape.

Status	`error`	Means	What to do
`401`	`unauthorized`	The sign-in token is missing, invalid or expired (it lasts an hour).	Sign in again: see API Keys.
`409`	`api_key_revoked`	`PATCH` on a revoked key: its cap no longer changes.	Mint a new key.
`409`	`api_key_active`	`DELETE` on an active key.	Revoke it first.

In a stream

Before the first chunk, a streamed call fails like any other: the status and body above. After the first chunk the status is already 200, so the stream ends with an error event instead of [DONE]:

CodeTEXT

`code`	Means	What to do
`job_failed`	The job failed after it started streaming.	Send the request again.
`stream_diverged`	The worker restarted its answer after the first chunks went out, so the text received is not the answer it committed on chain.	Discard the text and send the request again.

See Streaming.

Previous PageLimits Next PageAPI Reference

Explorer

APIs

Get Started

Errors

By code

Key management

In a stream