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.

StatusWhat to check
400JSON, parameters, model availability, endpoint or required streaming.
401Missing, invalid, expired or revoked key.
402Insufficient balance, key budget or account spending limit.
403Key or account permission.
404 / 405Unsupported endpoint or HTTP method.
413 / 415Text API body over 16 MB or Content-Type is not application/json.
429Rate limit. Honor Retry-After; gateway errors use 60 seconds.
502 / 503 / 504Model 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.

SymptomNext step
TOKELY_API_KEY is missingSet the variable in the terminal that runs your script; restart your server after changing environment variables.
Module not found / import errorInstall openai in the same Python environment or JavaScript project. Run JavaScript examples as .mjs files.
invalid_api_key / 401Use a Tokely key, copy its full value, and check that it is active and unexpired.
insufficient_quota / 402Check your account balance and key budget. Lower an unnecessarily high output limit.
model_not_availableCopy an enabled ID exactly and check that it supports the endpoint you selected.
stream_requiredAdd stream=true and read the request as a stream.
unsupported_parameterRemove the named field. Tokely supports a defined subset of model API options.
No text / finish_reason=lengthIncrease the output budget; reasoning models may use it for reasoning before visible text.
HTML or endpoint_not_supportedUse 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.

LimitValue
Request rate60 requests/minute per account, across keys.
JSON body16 MiB for Chat Completions / Responses; 256 KiB for media JSON requests.
Messages / input items1–128 per request.
Content parts1–32 per message when using an array.
Inline images / PDFsUp to 20 images and 4 PDFs per request; 10 MiB per decoded item.
Function tools32 maximum.
CompletionsOne per request (n=1).
Default output256 tokens, including reasoning.
Maximum outputModel limit capped at 262,144; 4,096 if unspecified.
Gateway timeout240 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.

EXPLORE DOCUMENTATION

IntroductionConnect your app to AI models through one familiar API. This is your guide to building with Tokely.QuickstartMake your first Tokely request in three steps.API keysConnect securely with a key from your Tokely dashboard.ModelsChoose an available model and use its exact ID in your request.PlaygroundUse the Tokely Playground to test prompts before writing code.Use your existing appConnect an existing OpenAI-compatible application to Tokely.Chat CompletionsGenerate responses from text messages and supported inline images or PDFs.ResponsesUse stateless text and supported multimodal input with the Responses API.EmbeddingsTurn text into vectors for search, RAG, clustering and classification with the OpenAI-compatible /v1/embeddings endpoint.Claude Code and the Messages APIPoint Claude Code or the Anthropic SDK at Tokely. Use the native /v1/messages endpoint with streaming, tools and prompt caching.Images and PDFsSend inline images and PDFs to compatible models through Chat Completions or Responses.Images, video & audioGenerate media with your Tokely API key and account balance.Errors & limitsDiagnose failed requests and keep your integration within service limits.StreamingDisplay generated text as it arrives with server-sent events.Function callingLet a model request a function, then execute it in your application.Structured outputRequest JSON output or a defined schema from a compatible model.Usage & billingModel prices, account balance and output reservations.WebhooksTokely webhook events, HMAC signature verification, delivery retries and replay behavior.
Use Tab to browse results ESC to close