2xx; client errors return 4xx; server or upstream errors return 5xx. This page documents the error model and how to respond to each case.
Error response shape
Error responses are always JSON with anerror object:
Status codes
400 — Bad Request
400 — Bad Request
The request payload is malformed: missing required parameter, wrong type, invalid JSON, or a value out of range.Common codes:
invalid_request, missing_parameter, invalid_parameter_type, json_parse_errorAction: Fix the request before retrying. Do not retry automatically.403 — Forbidden
403 — Forbidden
The key is valid but lacks permission for this endpoint, model, or region.Common codes:
insufficient_permissions, model_not_allowed, region_blockedAction: Check your workspace plan and per-key scopes. Contact support if the restriction is unexpected.404 — Not Found
404 — Not Found
The endpoint path, model ID, or resource ID does not exist.Common codes:
unknown_model, resource_not_found, unknown_endpointAction: Double-check the model name against the model catalog and the endpoint path against the API reference.422 — Unprocessable Entity
422 — Unprocessable Entity
Syntax is valid, but the request violates a business rule — e.g.,
max_tokens above the model’s limit, an unsupported combination of parameters, or content that violates the upstream provider’s safety policy.Common codes: max_tokens_exceeded, unsupported_parameter, content_policy_violationAction: Read the message carefully and adjust the payload. Do not retry blindly.429 — Too Many Requests
429 — Too Many Requests
You hit a rate limit — either your account RPM/TPM cap or the upstream provider’s throttle.Common codes:
rate_limit_exceeded, upstream_rate_limit, quota_exceededHeaders returned:Retry-After— seconds until the next attempt is allowedX-RateLimit-Limit— your current limitX-RateLimit-Remaining— requests remaining in the windowX-RateLimit-Reset— UNIX timestamp when the counter resets
500 — Internal Server Error
500 — Internal Server Error
An unexpected error on AIsa’s side. The
request_id field is critical for support investigation.Action: Retry with exponential backoff (see below). If the error persists, contact developer@aisa.one with the request_id.502 / 503 / 504 — Upstream Errors
502 / 503 / 504 — Upstream Errors
AIsa could not reach or got an error from the upstream model provider (OpenAI, Anthropic, etc.). Often transient.Common codes:
upstream_unavailable, upstream_timeout, gateway_errorAction: Retry with exponential backoff. For persistent issues, switch to an alternate model — the gateway can route Claude requests through different upstream deployments.Retry guidance
1
Only retry idempotent or safe-to-repeat calls
All
GET requests and most chat/completions calls are safe to retry. Do not blindly retry POST requests that create side effects (e.g., posting a tweet).2
Respect `Retry-After`
On 429 responses, always honor the
Retry-After header. On 5xx without Retry-After, fall back to exponential backoff.3
Use exponential backoff with jitter
Start with 1 s; double each attempt; add ±25% jitter; cap at 30 s.
4
Limit total retry time
Give up after 3–5 attempts or 60 s total — whichever comes first. Surface the error to the caller.
5
Never retry 4xx except 429
400, 401, 403, 404, and 422 indicate bugs in the request itself. Retrying will not help.Minimal retry example (Python)
Getting help
When reporting an issue to developer@aisa.one, include:- The
request_idfrom the error response - The HTTP status code and
error.code - Your model ID and a minimal reproduction (curl with a redacted key)
- The approximate timestamp of the failing request