Core concepts

Errors

Error shape and the stable status codes the API returns.

Errors return a JSON body with a stable code, a human-readable message, and the requestId for tracing:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
json · 7 lines

Status codes

StatusCodeMeaning
400invalid_requestMalformed, or missing a field
401unauthorizedMissing or invalid API key
402insufficient_fundsBalance too low for this call
402no_walletNo wallet on the billing chain
402no_delegationSpending not authorized yet
402no_pricingThe model has no price yet
402model_not_allowedYour key's policy blocks it
403forbiddenThe account is not active
403unsupported_clientMessages API outside Claude Code
413payload_too_largeBody over the 4 MB limit
429rate_limitedToo many requests
500internal_errorSomething failed on our side
503funds_unverifiableBalance could not be checked

Every 402 is fixed in the dashboard: add funds, or finish the wallet setup for that chain. Retry a 429 after its retry-after header, and a 500 or 503 shortly after; if a 500 persists, share its requestId.

The request body is capped at 4 MB. This is usually hit by base64-encoded attachments (images and PDFs), which inflate by about a third over their file size, so a ~3 MB image can push a request past the limit on its own. Downscale images, send a URL instead of inline base64 where the model supports it, or split a long conversation.

Rate-limit specifics live on the Rate limits page.

Errors | Roteo