Error Handling

BlockRun uses standard HTTP status codes and returns detailed error information.

HTTP Status Codes

Error Response Format

Gateway errors use the OpenAI envelope, with message and code mirrored at the top level for older clients. debug appears only when the fault is yours to fix — a 4xx such as an upstream rejecting one of your parameters — and then carries the upstream's description of it, redacted: credentials, URLs, deployment and account identifiers, and any routing infrastructure we do not sell under its own name are removed. A 429 or 5xx never carries upstream text: it describes our capacity or an upstream fault, which you cannot act on, so the body has just code and message (we keep the full text in our logs — quote the x-blockrun-gateway-request-id response header when you report one).

{
  "error": {
    "message": "Invalid request parameter — Message @bc1max on Telegram for help.",
    "type": "invalid_request_error",
    "code": "INVALID_PARAMETER",
    "param": null
  },
  "message": "Message @bc1max on Telegram for help.",
  "code": "INVALID_PARAMETER",
  "debug": "<the upstream's description of the rejected parameter, redacted>"
}

error.type is one of invalid_request_error, rate_limit_error, api_error, payment_required. The Anthropic-compatible /v1/messages endpoint answers in Anthropic's {"type":"error","error":{"type","message"}} shape and /v1/responses in OpenAI's {"error":{"message","type","param","code"}} shape instead.

Error codes

Errors after a stream has started

Once a stream: true response has begun, the status is already 200, so a failure arrives as a final SSE error event instead. Its message is fixed text ending in a code, never upstream text:

Billing for a cut-off stream follows the settlement rules for that endpoint: see the X-Payment-* response headers.

Common Errors

400 - Invalid Request

{
  "error": {"message": "Invalid request body", "type": "invalid_request_error", "code": "INVALID_REQUEST_BODY", "param": null},
  "message": "Invalid request body",
  "code": "INVALID_REQUEST_BODY",
  "details": [
    {"path": ["model"], "message": "Required"}
  ]
}

An unknown model is a plain-string error that suggests live IDs:

{"error": "Unknown model: openai/gpt-4. Try one of: openai/gpt-5.6-sol, …. Full list: GET /v1/models"}

Causes:

• Missing required fields (model, messages)
• Invalid model ID
• Malformed JSON
• A parameter the upstream model rejects (INVALID_PARAMETER) — the gateway surfaces these as 400, not 500

402 - Payment Required

{
  "x402Version": 2,
  "accepts": [{"scheme": "exact", "network": "eip155:8453", "amount": "246850", "asset": "0x8335…", "payTo": "0x…", "maxTimeoutSeconds": 300}],
  "error": "Payment Required",
  "message": "This endpoint requires x402 payment",
  "price": {"amount": "0.246850", "currency": "USD"},
  "paymentInfo": {"network": "base", "asset": "USDC", "x402Version": 2}
}

The signed requirements travel in the X-Payment-Required / PAYMENT-REQUIRED headers (and WWW-Authenticate: X402 requirements="…"), and — since 2026-08-30 — are mirrored at the top level of the JSON body too (x402Version, accepts), byte-identical to the decoded header. This is for v1-era x402 clients (early x402-fetch/x402-axios and third-party wrappers) that only parse the body and silently fail to auto-pay when there's no top-level accepts. price.amount equals the signed amount, including the flat $0.001 transaction fee. On chat, an exact payment is quoted and settled at input plus your full max_tokens as output (8192 when unset); see How the quote is computed.

402 - Payment Rejected

A PAYMENT-SIGNATURE that fails verification is answered with 402 and a machine-readable code (since 2026-08-26, on every BlockRun-native paid endpoint):

{
  "error": "Payment verification failed",
  "code": "PAYMENT_UNFUNDED",
  "message": "The payment authorization could not be executed on-chain. The usual cause is an insufficient USDC balance on Base for the quoted amount — …",
  "debug": "<facilitator reason>",
  "payer": "0x…"
}

Verification always runs before settlement, so none of these charged you. On the Solana gateway PAYMENT_VERIFICATION_UNAVAILABLE means the facilitator was unreachable — retry the same signed payment.

429 - Rate Limited

{
  "error": {"message": "Rate limited — … retry after 60s, or fail over to a same-tier model on a different provider.", "type": "rate_limit_error", "code": "RATE_LIMITED", "param": null},
  "code": "RATE_LIMITED",
  "source": "openai",
  "retry_after_seconds": 60
}

Headers: Retry-After: 60, X-RateLimit-Source: <model family>. Free models add FREE_TIER_RATE_LIMITED with X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset. See Rate Limits.

503 - Model Unavailable

{
  "error": {"message": "Model unavailable — Message @bc1max on Telegram for help.", "type": "api_error", "code": "MODEL_UNAVAILABLE", "param": null},
  "code": "MODEL_UNAVAILABLE"
}

Retry, or fail over to a same-tier model from a different family. Not settled.

500 - Server Error

{
  "error": {"message": "Unexpected error — Message @bc1max on Telegram for help.", "type": "api_error", "code": "INTERNAL_ERROR", "param": null},
  "message": "Message @bc1max on Telegram for help.",
  "code": "INTERNAL_ERROR"
}

Causes:

• Unclassified upstream error
• Temporary service issue

Settlement happens only after a successful upstream response, so a 500/503/504 never charges you.

SDK Error Classes

Troubleshooting

"Payment verification failed"

1. Read the code: PAYMENT_UNFUNDED → top up USDC on Base (or on Solana for sol.blockrun.ai)
2. PAYMENT_REPLAY → your client reused a nonce; sign a fresh authorization per request
3. PAYMENT_BLOCKHASH_STALE → re-sign; the Solana blockhash expired between signing and sending
4. PAYMENT_INVALID → confirm you signed the exact accepts[0] entry from the header (network, asset, amount, payTo) and that the wallet is on the right network

"Unknown model"

1. Check the model ID matches exactly (e.g., openai/gpt-5.5)
2. See available models for valid IDs

"Timeout"

1. Increase the timeout in client options
2. Try a faster model (e.g., gpt-5.4-mini instead of a -pro reasoning tier), or lower max_tokens — the gateway's own upstream timeout is 120s per call

"Network error"

1. Check your internet connection
2. Verify blockrun.ai/api is accessible

What's next?