Token101 DocsError Handling
Error envelope, common failure modes, and practical guidance for Token101 API clients.
Error Envelope
All Token101 v1 routes return a top-level error object when a request fails. The response format is:
{
"error": {
"type": "invalid_request_error",
"message": "Unsupported model",
"code": "invalid_request_error"
}
}The error object also carries a code field that mirrors type (same value); either can be used for programmatic branching. Some responses also include a detail object with additional context. Build client logic around error.type first, then treat message as the human-readable explanation you show to operators or end users.
Common Status Codes
| HTTP Status | Type | What it usually means | Recommended action |
|---|---|---|---|
| 400 | invalid_request_error | The request body failed schema validation or the requested model is not enabled. | Fix the payload, field names, or model ID before retrying. |
| 401 | authentication_error | The API key is missing, malformed, or unknown. | Send Authorization: Bearer sk-... and rotate invalid keys. |
| 402 | insufficient_quota | Held or actually charged credits were not enough to cover the call. | Add credits or move the user to a plan with available balance. |
| 403 | forbidden, account_suspended, permission_error | The account, plan, or upstream policy blocked the request. | Check billing state, plan entitlement, and account status. |
| 404 | not_found_error | A referenced resource — such as a prior response id in the Responses API — could not be found. | Check the id you referenced instead of retrying blindly. |
| 429 | rate_limit_exceeded | The request exceeded the current policy window. | Respect Retry-After, then retry with backoff. |
| 502 | upstream_error | Token101 could not get a response from the upstream model provider. | Retry idempotently; if it keeps failing, contact support. |
| 504 | timeout_error | The AI provider did not respond in time. | Retry with bounded deadlines and fewer concurrent retries. |
| 529 | overloaded_error | The model provider is temporarily overloaded. | Back off and retry after a short delay. |
Some 429 responses use the legacy type rate_limit_error instead of rate_limit_exceeded. Treat the two as the same condition — handle both when you branch on error.type.
Conversation Continuity (Responses API)
When you send previous_response_id on the Responses API, two distinct outcomes are possible, and they return different status codes. Branch on detail.reason to tell them apart:
| HTTP Status | detail.reason | What it means | Recommended action |
|---|---|---|---|
| 400 | responses_session_continuity_unavailable | This deployment cannot carry conversation continuity for the request. It is not silently ignored — you get an explicit error instead of a 2xx that quietly dropped the history. | Retry without previous_response_id and include the prior turns directly in the input of your request. |
| 404 | previous_response_not_found | Continuity is available, but the specific previous_response_id you referenced does not exist (expired or wrong id). | Check the id you referenced instead of retrying blindly. |
In short: responses_session_continuity_unavailable means "resend the earlier turns in the request", while previous_response_not_found means "the id you passed was wrong". A single-turn request that does not send previous_response_id is never affected.
Token Counting Source (count_tokens)
The Anthropic-compatible count_tokens preflight normally returns an exact upstream count. If that exact count cannot be obtained, Token101 falls back to a local estimate so your client can keep going. On the fallback path the response carries two headers so you can distinguish an estimate from an exact count:
x-token101-count-tokens-source: local_estimate— the returnedinput_tokensis a local estimate, not an exact upstream count.x-token101-count-tokens-fallback-reason— why the estimate was used (for example,upstream_status_401).
When the count is exact, neither header is present. Read x-token101-count-tokens-source to decide whether to treat the count as authoritative or to apply a conservative margin.
Practical Handling Tips
Use the HTTP status code for coarse control flow, error.type for programmatic branching, and detail.reason when it exists for product-specific messaging. Treat 400 and 401 as client-actionable bugs, 402/403/429 as billing or access restrictions, and 502/504 as temporary provider issues. When possible, return users to Rate Limits or Billing & Credits so they can resolve the issue without opening a support ticket.
Still Not Resolved?
If an error persists after you've checked the guidance above, email us at [email protected] and, where you can, include:
- The rough time it happened and the model you were using
- The full error response (JSON body)
- The call reference from the response headers, if any
We'll get back to you as soon as we can.