Operations
Errors
Handle common TokenAir API errors in an OpenAI-compatible integration.
Common status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request | Check JSON shape, required fields, and parameter names. |
| 401 | Authentication failed | Check that the API key is present and valid. |
| 403 | Access denied | Confirm the account has access to the requested model or feature. |
| 404 | Model or endpoint not found | Confirm the endpoint path and model ID. |
| 422 | Unsupported input | Adjust parameters for the selected model family. |
| 429 | Rate limited | Back off, retry later, or request higher limits. |
| 500-599 | Service or upstream error | Retry with backoff and inspect your request logs. |
Retry guidance
Retry transient 429 and 5xx responses with exponential backoff and jitter. Do not retry invalid 400-level requests without changing the request.
first retry: 1s
second retry: 2s
third retry: 4s
add jitter: random 0-500msDo not retry these blindly
- 401: fix the API key or environment variable.
- 403: confirm account access to the model or feature.
- 404: confirm the endpoint path and model ID.
- 400/422: fix the request body before retrying.
Log safely
Log request IDs, status codes, model IDs, latency, and token counts. Do not log API keys. Avoid logging sensitive prompt or user data unless your own privacy policy and retention rules allow it.