Errors
API errors are OpenAI-shaped. Payment errors are x402-shaped. Both are JSON.
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 allowed range |
| 401 | invalid_api_key | Unknown, revoked or wrong-mode key |
| 402 | insufficient_balance | Key balance cannot cover this call. Top up. |
| 404 | model_not_found | Not in the catalog |
| 429 | model_overloaded | Model at capacity. Retry in a few seconds. |
| 502 | upstream_error | Temporarily unavailable. You are not charged. |
Payment errors
A rejected payment returns 402 with a code and an empty accepts:
{ "x402Version": 2, "error": "client amount=1200 does not match required 1310", "code": "terms_mismatch", "accepts": [] }bad_payload,unsupported_version: the header is not a valid x402 v2 payloadterms_mismatch: what you signed is not what was quoted (amount, asset, network or recipient)verify_invalid: the facilitator rejected the signature or the balancepayment_replayed: this authorization was already used. Sign a new 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 includes an x402 receipt stating what happens to your money. Failed calls are refunded in full.