Error Codes — TokSpan Docs

HTTP Status Codes

Code	Meaning	Action
400	Bad Request	Check your request body for malformed JSON or missing required fields
401	Unauthorized	Verify your API key is correct and active in the dashboard
404	Invalid URL / Endpoint Not Found	Check the request path against the API reference
429	Rate Limited / Insufficient Quota	For rate limits, implement exponential backoff with jitter. If the error mentions quota or balance (e.g. `insufficient_user_quota`), top up in the Dashboard instead of retrying — see rate limits
500	Internal Error	TokSpan-side issue — retry with backoff or contact support
502	Bad Gateway	Upstream provider error — auto-failover may activate
503	Service Unavailable / Model Not Found	Temporary overload — retry with backoff. If the error carries code `model_not_found`, the model isn't available to your key — check the model name in the model catalog

Error Response Format

Errors are returned with an error object containing a human-readable message and a type identifier. On TokSpan the type is usually new_api_error, and account-balance errors carry code: "insufficient_user_quota". Example:

json
{
  "error": {
    "message": "You can access all models, but this request exceeded your account balance. Please top up at the Dashboard.",
    "type": "new_api_error",
    "param": null,
    "code": "insufficient_user_quota"
  }
}

Checking the message matters. A 429 with a rate-limit message means back off and retry; a 429 (or 400) with a quota message means add credits first. Read the message before deciding how to react. The message wording shown here is illustrative — always rely on the HTTP status code and the code field.