API reference

Errors

Reference for HTTP status codes and error shapes.

Last updated: 2026-05-19

All endpoints return errors in the OpenAI-compatible shape:

{
  "error": {
    "message": "human-readable description",
    "type":    "category",
    "code":    "specific_code"
  }
}

Status code map

HTTP	Type	Code	Meaning	What to do
400	`invalid_request_error`	`bad_request`	Malformed body, missing required field	Fix client payload
400	`invalid_request_error`	`unknown_tier`	Tier name unrecognised	Use `slow / medium / fast / ludicrous`
401	`invalid_request_error`	`invalid_api_key`	Key missing / malformed / revoked	Check / rotate key in dashboard
401	`invalid_request_error`	`expired_token`	JWT expired	`POST /auth/refresh` (mobile API)
403	`permission_denied`	`tier_not_allowed`	Plan doesn't include this tier	Upgrade plan or use a lower tier
403	`permission_denied`	`account_disabled`	Account suspended	Contact support
404	`not_found`	`model_not_found`	`model_id` not in catalog	Check Models catalog
404	`not_found`	`kb_not_found`	Knowledge base does not exist or not yours	Verify slug + auth
413	`invalid_request_error`	`payload_too_large`	Upload > 50 MB	Split or compress
422	`invalid_request_error`	`context_too_long`	Prompt + max_tokens > model context	Reduce prompt or `max_tokens`
429	`rate_limit_exceeded`	`rate_limit_exceeded`	RPM exceeded	Backoff — see Rate limits
500	`server_error`	`internal_error`	Bug on our side	Retry, then report with `X-Request-Id`
502	`bad_gateway`	`backend_unavailable`	Upstream model server returned error	Auto-retried on alt backend if available
503	`service_unavailable`	`all_backends_down`	All backends serving this model are down	Pick another model temporarily; check Fleet
504	`gateway_timeout`	`backend_timeout`	Inference timed out	Reduce `max_tokens` or retry

When you hit a 5xx and want to report it:

curl ... -i 2>&1 | tee /tmp/siati-call.log

Send us the X-Request-Id from the response — we can trace the request through the BackendRouter and find the upstream cause within seconds.