API REFERENCE
Errors & limits
Diagnose failed requests and keep your integration within service limits.
HTTP status codes
Errors use an OpenAI-style error object. Save the X-Request-ID response header in your logs to identify the request.
| Status | What to check |
|---|---|
| 400 | JSON, parameters, model availability, endpoint or required streaming. |
| 401 | Missing, invalid, expired or revoked key. |
| 402 | Insufficient balance, key budget or account spending limit. |
| 403 | Key or account permission. |
| 404 / 405 | Unsupported endpoint or HTTP method. |
| 413 / 415 | Text API body over 16 MB or Content-Type is not application/json. |
| 429 | Rate limit. Honor Retry-After; gateway errors use 60 seconds. |
| 502 / 503 / 504 | Model service error, unavailability or timeout. |
{
"error": {
"message": "Your Tokely balance or API key budget is insufficient for this request.",
"type": "invalid_request_error",
"param": null,
"code": "insufficient_quota"
}
}Fix your first request
Start with the smallest request from Quickstart. Check the HTTP status and error.code before changing model settings. If your SDK fails before sending HTTP, check the local setup first.
| Symptom | Next step |
|---|---|
| TOKELY_API_KEY is missing | Set the variable in the terminal that runs your script; restart your server after changing environment variables. |
| Module not found / import error | Install openai in the same Python environment or JavaScript project. Run JavaScript examples as .mjs files. |
| invalid_api_key / 401 | Use a Tokely key, copy its full value, and check that it is active and unexpired. |
| insufficient_quota / 402 | Check your account balance and key budget. Lower an unnecessarily high output limit. |
| model_not_available | Copy an enabled ID exactly and check that it supports the endpoint you selected. |
| stream_required | Add stream=true and read the request as a stream. |
| unsupported_parameter | Remove the named field. Tokely supports a defined subset of model API options. |
| No text / finish_reason=length | Increase the output budget; reasoning models may use it for reasoning before visible text. |
| HTML or endpoint_not_supported | Use https://api.tokely.me/v1 as the SDK base URL. Append /chat/completions only for a direct HTTP request. |
Service limits
Model-specific context, output and feature limits also apply.
| Limit | Value |
|---|---|
| Request rate | 60 requests/minute per account, across keys. |
| JSON body | 16 MiB for Chat Completions / Responses; 256 KiB for media JSON requests. |
| Messages / input items | 1–128 per request. |
| Content parts | 1–32 per message when using an array. |
| Inline images / PDFs | Up to 20 images and 4 PDFs per request; 10 MiB per decoded item. |
| Function tools | 32 maximum. |
| Completions | One per request (n=1). |
| Default output | 256 tokens, including reasoning. |
| Maximum output | Model limit capped at 262,144; 4,096 if unspecified. |
| Gateway timeout | 240 seconds. Public proxy limits may be shorter for non-streaming requests. |
Retry deliberately
Fix authentication, balance and validation errors before retrying. For transient errors, use bounded backoff and honor Retry-After. Avoid immediately replaying after a timeout: generation may already have begun.
The gateway forwards each request once. The engine can try another compatible route after an eligible failure, within its retry budget. Use Idempotency-Key for images and media task submissions: generate a new key for each intended generation and retain the same key and request body for every recovery attempt. A repeated key returns the original task, even after a disconnect or engine restart, without another generation or charge. A different body with that key returns HTTP 409. The website stores this key and offers Recover previous result. Accepted tasks continue to be polled through temporary supplier outages; polling errors alone do not trigger another paid generation. Accepted media tasks and partially delivered responses must not be blindly resubmitted. Models with a single configured route have no route fallback. SDK retry settings are separate; retrying a submission can start new billable work.