Errors
Use the HTTP status and the shared JSON error envelope.
API errors use one JSON shape:
{"code": "invalid_key", "message": "A valid API key is required."}Branch on the HTTP status and stable code, not the prose in message. Intermediaries can still return non-JSON failures; treat those as transport failures rather than successful decisions.
| Status | Meaning | Your next step |
|---|---|---|
400 | Malformed JSON, compression, or request rules | Fix the body or headers |
401 | Missing, invalid, or revoked bearer key | Fix credentials; do not blindly retry |
413 | Body, formatted token count, or option count too large | Reduce the request; no automatic truncation |
415 | Unsupported content type or content encoding | Use JSON and a supported single encoding |
422 | Wrong fields, duplicate IDs, invalid levels, or unavailable model | Fix the schema or model ID |
429 | Key or account rate limit reached | Honor Retry-After and back off |
502 | Invalid or unavailable inference response | Retry within a bounded budget |
503 | Gateway temporarily unavailable | Retry within a bounded budget |
504 | Inference timed out | Retry within a bounded budget |
529 | Inference overloaded | Back off and reduce concurrency |
If inference fails, do not manufacture an answer or proceed as if the gate passed. Queue review or return a temporary failure from your own application.
The SDKs retry 429 and server errors with bounded backoff. Apply a separate application timeout and avoid wrapping SDK retries in an unbounded retry loop. Authentication and validation errors need corrected input.