Errors & Status Codes

Standard HTTP error codes, JSON error responses, common error types, and automatic retry patterns.

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

StatusCode NameMeaning & Resolution
400Bad RequestMalformed JSON payload or invalid parameters.
401UnauthorizedInvalid or revoked API key. Verify your Bearer token.
402Payment RequiredPrepaid USD balance depleted. Top up funds to resume.
404Not FoundSpecified model ID does not exist. Check Model Directory.
429Rate LimitedConcurrency or RPM limit hit. Apply exponential backoff.
502Bad GatewayUpstream provider timeout. Failed requests are never charged.
503Service UnavailableModel 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)