Docs

Errors

Errors use OpenAI's envelope, so SDK error classes map cleanly. The rule that matters: a failed request is never a billed request.

Error shape

{
  "error": {
    "message": "Insufficient credits. This request may cost up to 0.0301 USD. Top up at the dashboard.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type groups the family, code (when present) names the exact condition, and message is safe to log and show to humans.

Status codes

Status	Code	Meaning	Charged
400	invalid_request_error	Bad JSON, missing model or messages, invalid max_tokens.	No
401	invalid_api_key	Missing, malformed, or revoked key.	No
402	insufficient_quota	Balance cannot cover the request's worst case. Top up.	No
404	model_not_found	The model id is not in the catalog.	No
413	file_too_large	Batch input file over the size limit.	No
429	rate_limit_error	Requests per minute exceeded. Honor Retry-After.	No
429	monthly_key_limit_exceeded	This key's monthly spend cap is exhausted.	No
4xx	(engine)	The engine rejected the request, e.g. prompt over the context window. Forwarded verbatim.	No
502	server_error	The upstream GPU failed, timed out, or failed TLS verification.	No
503	server_error	No live backend is serving this model right now.	No

A 503 means the model has no live GPU behind it at this moment. The Batch API accepts work during exactly that state and runs it when capacity returns.

Handling in SDKs

import openai
from openai import OpenAI

client = OpenAI(base_url="https://tokenkiln.com/api/v1", api_key="tk_...")

try:
    response = client.chat.completions.create(
        model="Qwen/Qwen2.5-7B-Instruct",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except openai.RateLimitError as e:
    retry_after = e.response.headers.get("retry-after")
    print(f"429, retry in {retry_after}s")
except openai.APIStatusError as e:
    # 402 insufficient_quota, 404 model_not_found, 5xx upstream...
    print(e.status_code, e.response.json()["error"]["code"])

Retry guidance

429: wait the number of seconds in the Retry-After header, then retry.
502 and 503: retry with exponential backoff. Since failed requests are never billed, retrying an errored call cannot double-charge you.
402: not retryable; top up or enable auto top-up on the Credits page.
When contacting support, include the response's x-request-id header.