Errors
API errors follow the OpenAI shape. Payment errors follow x402. Both are JSON.
Preview specification. The API opens at launch; this page describes the interface it will serve.
API errors
{ "error": { "message": "...", "type": "invalid_request_error", "code": "model_not_found" } }| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_max_tokens | max_tokens must be a positive integer |
| 400 | invalid_amount | Deposit outside the accepted range |
| 401 | invalid_api_key | Unknown, revoked or wrong-network key |
| 402 | insufficient_balance | The key cannot cover this call. Top it up. |
| 404 | model_not_found | Not in the catalog |
| 429 | model_saturated | Every upstream for this model is busy. Retry shortly. |
| 502 | upstream_error | No upstream answered. You are not charged. |
Payment errors
A refused payment returns 402 with a code and an empty list of accepted offers:
{ "x402Version": 2, "error": "signed amount 900 does not match quoted 1040", "code": "terms_mismatch", "accepts": [] }bad_payload,unsupported_version: the header is not a valid x402 v2 payloadterms_mismatch: what was signed differs from the quote (amount, asset, network or recipient)verify_invalid: the signature or the balance did not check outpayment_replayed: this authorization was already used. Sign a fresh one.settle_failed: nothing moved. Safe to retry.settle_unconfirmed: settlement could not be confirmed. Check the transaction before retrying.
When a paid call fails
The error body carries a receipt that says what happens to the payment. A call that fails upstream is refunded in full.