Error Handling

Running into errors when calling the API? This page lists common error codes, their causes, and troubleshooting tips. In most cases, the message field in the error response explains the issue directly—check it first.

Common Error Codes

Code	Meaning	Common Causes & What to Do
400	Bad Request	Invalid parameters. Refer to the error message and fix the request parameters
401	Unauthorized	API Key is missing or incorrect. Check that the Authorization: Bearer API_KEY header is set correctly
403	Forbidden	Insufficient account balance or insufficient permissions. The most common permission issue is that the model requires identity verification; for other cases, refer to the error message
404	Task Not Found	When querying or continuing an async task (e.g. extend, remix), the task ID doesn't exist, has expired, or doesn't belong to your account. The ID is included in the error message
429	Rate Limited	You've hit a rate limit. Check the message to see which limit was triggered (RPM / TPM, etc.)—see Rate Limits. It can also happen when invalid parameters cause repeated retries that eventually trigger throttling
500	Internal Server Error	An unknown server error occurred. Note the Request ID and contact support
503 / 504	Service Unavailable	Usually caused by high system load—retry shortly. For chat requests, consider enabling streaming ("stream": true) to reduce timeouts

Reading Error Responses

Error responses are typically JSON objects containing the error code, message, and request ID:

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient account balance. Please top up and try again. (request id: 202511162255194339355347BE3UyUY)",
    "type": "api_error"
  }
}

• message: The most direct description of the problem—read this first
• code / type: Useful for programmatic error classification
• Request ID: Include this when contacting support to speed up troubleshooting significantly

Retry Recommendations

• Retryable errors (429, 500, 503, 504): Retry with exponential backoff—e.g. wait 1s, 2s, 4s... up to 3–5 attempts
• Non-retryable errors (400, 401, 403, 404): Fix the parameters, key, or permissions first. Blind retries only waste quota and may trigger rate limits
• Set reasonable timeouts in your client to avoid requests hanging indefinitely

Automatic Node-Level Retries

Every model on Calgine Tokens is backed by multiple provider nodes. When a single node fails, the system automatically retries on another node—fully transparent to your code. See Providers & Routing.

Still Stuck?

Contact support with the following information:

• The complete error response (including the message)
• The Request ID
• The model used and the time of the request