Toknix returns standard HTTP status codes. Statuses in the 2xx range indicate success, 4xx indicate client-side validation errors, and 5xx indicate gateway or upstream provider failures.
HTTP Status Codes
| Status | Code Name | Meaning & Resolution |
|---|---|---|
400 | Bad Request | Malformed JSON payload or invalid parameters. |
401 | Unauthorized | Invalid or revoked API key. Verify your Bearer token. |
402 | Payment Required | Prepaid USD balance depleted. Top up funds to resume. |
404 | Not Found | Specified model ID does not exist. Check Model Directory. |
429 | Rate Limited | Concurrency or RPM limit hit. Apply exponential backoff. |
502 | Bad Gateway | Upstream provider timeout. Failed requests are never charged. |
503 | Service Unavailable | Model temporarily overloaded. Automatic fallback available. |
Error Payload Schema
json
{
"error": {
"message": "Your account balance is insufficient to complete this request ($0.00 available).",
"type": "insufficient_funds_error",
"param": null,
"code": "insufficient_balance"
}
}Recommended Retry Strategy
When experiencing 429 or 5xx errors, implement exponential backoff with jitter:
python
import time, random
def call_with_retry(fn, max_retries=3):
for attempt in range(max_retries):
try:
return fn()
except Exception as e:
if attempt == max_retries - 1:
raise e
sleep_time = (2 ** attempt) + random.uniform(0.1, 0.5)
time.sleep(sleep_time)