Skip to main content
Every AIsa API response follows standard HTTP semantics. Successful calls return 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 an error object:

Status codes

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.
No API key, malformed Authorization header, or the key is invalid/revoked.Common codes: missing_api_key, invalid_api_key, revoked_api_keyAction: Verify the key in your Dashboard and resend with Authorization: Bearer YOUR_AISA_API_KEY.
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.
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.
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.
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 allowed
  • X-RateLimit-Limit — your current limit
  • X-RateLimit-Remaining — requests remaining in the window
  • X-RateLimit-Reset — UNIX timestamp when the counter resets
Action: Back off and retry (see Retry guidance below). See Rate Limits for the full quota table.
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.
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_id from 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