Documentation

Tokenless speaks the APIs you already use: OpenAI Chat Completions and Responses, plus Anthropic's Messages API. Point your existing SDK at our base URL, drop in one key, and keep your code.

Quickstart

  1. Create an account, verify your email, and grab a key from the dashboard. (Email verification is required before a key can be created.)
  2. Add a little balance under Billing (your first $1 is free).
  3. Make your first call:
quickstart.sh
curl https://api.tokenless.store/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus-4.8",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
Base URL. All requests go to https://api.tokenless.store/api/v1. The API is OpenAI-compatible, so most SDKs work by setting this as the base URL and your key as the API key. (The Anthropic SDK takes https://api.tokenless.store/api and adds /v1 itself.)

Example scripts

A tiny command-line script in three flavors. Paste your API key in place of sk-tk-YOUR_KEY_HERE (or set TOKENLESS_API_KEY), set MODEL and REASONING, and pass your prompt as a command-line argument. The TypeScript and Python versions need no SDK.

ask.ts
// Run:  npx tsx ask.ts "How many moons does Jupiter have?"
const API_KEY = process.env.TOKENLESS_API_KEY ?? "sk-tk-YOUR_KEY_HERE";
const BASE_URL = "https://api.tokenless.store/api/v1";

// --- set these however you like ---
const MODEL = "opus-4.8";      // any id: fable-5, gpt-5.5, sonnet-5, ...
const REASONING = "";          // "" | low | medium | high | extra | ultra
const prompt = process.argv.slice(2).join(" ") || "Hello!";

const res = await fetch(BASE_URL + "/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: prompt }],
    ...(REASONING ? { reasoning_effort: REASONING } : {}),
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? ("HTTP " + res.status));
console.log(data.choices[0].message.content);
ask.py
# Run:  python ask.py "How many moons does Jupiter have?"
import os, sys, json, urllib.request, urllib.error

API_KEY = os.environ.get("TOKENLESS_API_KEY", "sk-tk-YOUR_KEY_HERE")
BASE_URL = "https://api.tokenless.store/api/v1"

# --- set these however you like ---
MODEL = "opus-4.8"        # any id: fable-5, gpt-5.5, sonnet-5, ...
REASONING = ""            # "" | low | medium | high | extra | ultra
prompt = " ".join(sys.argv[1:]) or "Hello!"

body = {"model": MODEL, "messages": [{"role": "user", "content": prompt}]}
if REASONING:
    body["reasoning_effort"] = REASONING

req = urllib.request.Request(
    BASE_URL + "/chat/completions",
    data=json.dumps(body).encode(),
    headers={"Authorization": "Bearer " + API_KEY, "Content-Type": "application/json"},
)
try:
    with urllib.request.urlopen(req) as r:
        print(json.load(r)["choices"][0]["message"]["content"])
except urllib.error.HTTPError as e:
    print("Error:", e.read().decode(), file=sys.stderr)
ask.sh
#!/usr/bin/env bash
# Needs curl + jq.  Run:  ./ask.sh "How many moons does Jupiter have?"
API_KEY="sk-tk-YOUR_KEY_HERE"     # or: API_KEY="$TOKENLESS_API_KEY"
BASE_URL="https://api.tokenless.store/api/v1"

# --- set these however you like ---
MODEL="opus-4.8"                  # any id: fable-5, gpt-5.5, sonnet-5, ...
REASONING=""                      # "" | low | medium | high | extra | ultra
PROMPT="$*"
[ -z "$PROMPT" ] && PROMPT="Hello!"

BODY=$(jq -n --arg m "$MODEL" --arg p "$PROMPT" --arg r "$REASONING" \
  '{model:$m, messages:[{role:"user",content:$p}]} + (if $r=="" then {} else {reasoning_effort:$r} end)')

curl -s "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$BODY" | jq -r '.choices[0].message.content'

Swap MODEL for any id from Models and set REASONING to any level from Reasoning effort. To stream the response, add stream: true. See Streaming.

Authentication

Authenticate with a bearer token in the Authorization header. Keys start with sk-tk- and are shown once at creation, so store them securely. You can rotate them from the dashboard anytime.

bash
Authorization: Bearer sk-tk-xxxxxxxxxxxxxxxxxxxxxxxx

The Messages API also accepts the Anthropic SDK's x-api-key header, so that SDK works with no extra configuration.

Chat completions

POST /api/v1/chat/completions follows the OpenAI schema for requests and responses, and it works for every model, GPT and Claude alike. This is the portable surface. Reach for the native Responses or Messages APIs when you want a provider's own shape.

chat.py
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenless.store/api/v1",
    api_key="sk-tk-...",
)

resp = client.chat.completions.create(
    model="opus-4.8",
    messages=[{"role": "user", "content": "Write a haiku about glass."}],
)
print(resp.choices[0].message.content)
print(resp.usage)  # includes prompt/completion tokens and cost

The response (OpenAI shape):

chat.response.json
{
  "id": "cmpl_...",
  "object": "chat.completion",
  "created": 1719800000,
  "model": "opus-4.8",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Clear panes of morning…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14, "completion_tokens": 19, "total_tokens": 33,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0,
    "cost": 0.000512
  }
}
  • Output cap. Set max_completion_tokens or the older max_tokens (if you send both, max_completion_tokens wins). Without either, GPT and Gemini models get up to 32,000 tokens, because their thinking is spent from the same cap as the answer, and Claude gets 4,096. When your balance is too low to hold a 32,000-token reply, the default shrinks to what it can cover (never below 4,096) instead of failing. A reply that hits the cap ends with finish_reason: "length".
  • One choice per request. n greater than 1 returns a 400; send separate requests for several completions.
  • Full responses. Structured output refusals (refusal), annotations, and logprobs come back as OpenAI sends them, streaming or not.
  • Roles. system, developer, user, assistant, and tool. Claude and Gemini models receive developer messages as system.
  • Everything else passes through. Fields such as tools, response_format, top_p, and seed reach the model unchanged.

Responses API (OpenAI models)

POST /api/v1/responses follows OpenAI's Responses schema. The prompt is input (a string or items), the cap is max_output_tokens (default 32,000, scaled down to what a low balance can hold), and effort nests under reasoning. OpenAI models only: Claude ids return a 400 pointing you at /chat/completions or /messages.

responses.sh
curl https://api.tokenless.store/api/v1/responses \
  -H "Authorization: Bearer sk-tk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain entanglement simply.",
    "reasoning": { "effort": "high" }
  }'

The response is the canonical Responses shape: an output array of typed items, with output_text as a convenience.

responses.response.json
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1719800000,
  "model": "gpt-5.5",
  "status": "completed",
  "output": [
    // a reasoning item appears here only when include_reasoning is set (see below)
    {
      "id": "msg_...", "type": "message", "status": "completed", "role": "assistant",
      "content": [{ "type": "output_text", "text": "Entanglement is…", "annotations": [] }]
    }
  ],
  "output_text": "Entanglement is…",
  "usage": {
    "input_tokens": 12, "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 88, "total_tokens": 100,
    "cost": 0.00135
  }
}

Messages API (Claude models)

POST /api/v1/messages is Claude's native format, so you can point the Anthropic SDK straight at the API. system is top-level, and max_tokens defaults to 4096 if you omit it (native Anthropic requires it; we fill in a default). Claude models only.

messages.sh
curl https://api.tokenless.store/api/v1/messages \
  -H "Authorization: Bearer sk-tk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus-4.8",
    "max_tokens": 1024,
    "system": "You are concise.",
    "messages": [{ "role": "user", "content": "Explain entanglement simply." }]
  }'

The response is Anthropic's native shape: a content array of typed blocks. With thinking on, a thinking block precedes the text (see Reasoning effort).

messages.response.json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "opus-4.8",
  "content": [
    // { "type": "thinking", "thinking": "…", "signature": "…" }  (only when thinking is on)
    { "type": "text", "text": "Entanglement is…" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 16, "output_tokens": 74,
    "cache_creation_input_tokens": 0,
    "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 },
    "cache_read_input_tokens": 0, "cost": 0.00097
  }
}
Using the Anthropic SDK? Set base_url to https://api.tokenless.store/api (the SDK appends /v1/messages for you). Anthropic's own model ids such as claude-opus-4-8 work as-is, so code written for the Anthropic API needs no model renames.

Counting tokens. POST /api/v1/messages/count_tokens takes the same model, messages, system, and tools and returns { "input_tokens": N }, so the SDK's countTokens() works. It's free. The count is an estimate (about 4 characters per token, 5,000 per image), good for sizing a prompt; the exact count is in each response's usage.

Tool calling

Pass tools and tool_choice exactly as you would to the provider directly. They are forwarded through untouched, and the model's tool calls come back in the standard shape, so agent frameworks work without changes. Supported on all three surfaces, streaming and non-streaming alike: Chat completions, Responses, and Messages.

tools.py
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenless.store/api/v1",
    api_key="sk-tk-...",
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "What's the weather in Paris?"}]

resp = client.chat.completions.create(
    model="opus-4.8",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

msg = resp.choices[0].message
if msg.tool_calls:                     # finish_reason == "tool_calls"
    call = msg.tool_calls[0]
    result = run_your_tool(call.function.name, call.function.arguments)

    # Send the model's own turn back, then the result keyed by tool_call_id.
    messages.append(msg)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": result,
    })

    final = client.chat.completions.create(
        model="opus-4.8", messages=messages, tools=tools,
    )
    print(final.choices[0].message.content)

When the model calls a tool, content is null and finish_reason is tool_calls:

tools.response.json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

When streaming, tool calls arrive as incremental deltas keyed by index. The function name comes first and the arguments JSON is split across later chunks, so concatenate the fragments before parsing. Official SDKs reassemble this for you.

Tool definitions are billed as input. Your tools schemas are part of the prompt on every call, and a large toolset can run to tens of thousands of tokens per request. Send only the tools a step actually needs, and check usage.prompt_tokens to see the real cost.

Coding agents (Codex)

The Codex app and CLI talk to the Responses API, so they work against Tokenless as a custom model provider. Add this to ~/.codex/config.toml:

~/.codex/config.toml
model = "gpt-6-astra"
model_provider = "tokenless"
model_reasoning_effort = "medium"

[model_providers.tokenless]
name = "Tokenless"
base_url = "https://api.tokenless.store/api/v1"
wire_api = "responses"
# Read by the desktop app too, which does not see your shell environment.
experimental_bearer_token = "sk-tk-..."
supports_websockets = false

Set model to any GPT id from Models (the Responses API is OpenAI-only; for Claude, point a Claude-native tool at the Messages API instead). Remove the model_provider line to switch back to your default provider.

Agents are token-hungry. Every turn resends the conversation and the full tool schema, so a single task can run to hundreds of thousands of tokens. Keep auto-reload on, and watch the first few tasks on your usage page. Prompt caching cuts most of the repeat cost automatically.

Reasoning effort

Optionally control how much a model thinks with reasoning_effort. Six levels, in order: minimal · low · medium · high · extra · ultra. It's opt-in: omit it and each provider's own default applies. Thinking tokens count as output, so higher effort costs more, and it's metered exactly.

For most Claude models, the level sets the extended-thinking token budget, literally how much thinking the model may do:

  • low 4K · medium 8K · high 16K · extra 32K thinking tokens
  • ultra: uncapped, all remaining room under the model's max output
  • minimal: thinking off

Budgets are a ceiling. Claude thinks adaptively and often uses far less. The thinking budget is only served on the Messages API, where we automatically raise max_tokens so the chosen level fits alongside the answer. (A few newer models take an effort setting rather than a fixed token budget; the level scales their thinking the same way.)

Higher levels hold more balance. Because we raise max_tokens to fit the thinking, a higher level places a larger up-front hold on your balance, and ultra holds against the model's full output cap. The unused hold is refunded after metering (thinking is adaptive and usually costs far less), so you're only charged for what you use. A low balance can still get a 402 on a big ultra request. Drop to a lower level or add balance if that happens.
  • Messages (Claude): reasoning_effort selects the thinking budget, or pass Anthropic's native thinking block for full control.
  • Chat Completions: reasoning for GPT models. Claude thinking is not enabled on this surface; use the Messages API for Claude thinking.
  • Responses (OpenAI): nested reasoning: { effort }.

One knob, two native mechanisms. GPT uses OpenAI's discrete effort enum; Claude uses a thinking-token budget or, on a few newer models (e.g. Fable 5), an effort setting. We translate your level to each:

reasoning_effortGPT (OpenAI effort)Claude (thinking budget*)
minimalminimal (GPT-6 Luna: none)off
lowlow4K tokens
mediummedium8K tokens
highhigh16K tokens
extrahigh (GPT-6: xhigh)32K tokens
ultrahigh (GPT-6: max; GPT-6 Luna: xhigh)uncapped

* A few newer Claude models (e.g. Fable 5) use the effort setting directly rather than a token budget: extra → xhigh, ultra → max. Same knob, same scaling.

OpenAI's standard enum stops at high, so on GPT-5.x extra and ultra are sent as high. The GPT-6 family reaches higher: extra maps to xhigh and ultra to max (GPT-6 Luna tops out at xhigh and turns thinking off with none). For full control on Claude, skip the level and pass Anthropic's native thinking block yourself (below); it's forwarded as-is.

reasoning.json
// Messages: pick a level; max_tokens is auto-bumped to fit the budget
{ "model": "opus-4.8", "max_tokens": 2048, "messages": [/* … */],
  "reasoning_effort": "extra" }

// "ultra": uncapped thinking (bounded only by the model's max output)
{ "model": "opus-4.8", "max_tokens": 2048, "messages": [/* … */],
  "reasoning_effort": "ultra" }

// …or the native Anthropic block, forwarded as-is
{ "model": "opus-4.8", "max_tokens": 8192, "messages": [/* … */],
  "thinking": { "type": "enabled", "budget_tokens": 4096 } }

// Chat Completions / Responses: reasoning for GPT models
{ "model": "gpt-5.5", "messages": [/* … */], "reasoning_effort": "high" }

Getting the thinking back

By default only the answer comes back. Whether, and how, you receive the thinking depends on the surface.

Claude: Messages API

Thinking is automatic whenever it's on, no flag needed. A thinking block appears in content before the text block; with stream: true it arrives as native content_block_delta events ahead of the answer. How much thinking text you see varies by model and prompt: some models return it in full, others run the thinking but return little or none of its text, and easy prompts may not think at all. The output token count always reflects what ran.

messages-thinking.sh
curl https://api.tokenless.store/api/v1/messages \
  -H "Authorization: Bearer sk-tk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus-4.8",
    "max_tokens": 2048,
    "messages": [{ "role": "user", "content": "Prove there are infinitely many primes." }],
    "reasoning_effort": "high",
    "stream": true
  }'
# → content_block (thinking) deltas, then content_block (text) deltas, then message_delta usage

GPT: Chat Completions & Responses

Opt in with include_reasoning: true. Where it lands:

  • Chat Completions: message.reasoning_content (non-stream) or delta.reasoning_content chunks, emitted before the answer (stream).
  • Responses: a reasoning item with summary_text in output (non-stream) or response.reasoning_summary_text.delta events (stream).

OpenAI hides the raw chain-of-thought, so these fields may be empty even when reasoning ran. The token usage still reflects it.

gpt-reasoning.sh
curl https://api.tokenless.store/api/v1/chat/completions \
  -H "Authorization: Bearer sk-tk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{ "role": "user", "content": "Prove there are infinitely many primes." }],
    "reasoning_effort": "high",
    "include_reasoning": true
  }'

# Non-streaming response carries the reasoning alongside the answer:
# {
#   "choices": [{ "message": {
#     "role": "assistant",
#     "reasoning_content": "…",   ← present when include_reasoning is set
#     "content": "There are infinitely many primes because…"
#   }}], "usage": { … }
# }

Streaming

Set stream: true to receive Server-Sent Events. Tokens stream incrementally over a long-lived connection, and on Chat Completions the final event carries usage and cost (on by default; turn it off with stream_options: { include_usage: false }).

stream.ts
const stream = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Stream a story." }],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

If a request can't start (bad input, no balance, or the model is unavailable), you get a normal HTTP error status before any events, exactly as without streaming. If a stream fails after it has begun, it ends with an error event instead of a normal finish, so a cut-off answer is never mistaken for a complete one. While a model thinks silently, the stream sends a : keep-alive comment every 15 seconds so proxies don't close it; SSE clients ignore these lines. See Errors & retries.

Models

For image and video generation, see the Media API and Studio documentation. Media uses separate pricing units and asynchronous jobs.

GET /api/v1/models returns the catalog with per-token pricing for text and capability-specific pricing for media. GET /api/v1/models/{id} returns one model. Pass a model's id as the model field.

Common alternate spellings resolve to the same model, so existing code rarely needs renames: Anthropic's own ids (claude-opus-4-8, claude-sonnet-5-5), router-style prefixes (anthropic/claude-opus-4.8, openai/gpt-5.5), and the short names opus, sonnet, and haiku, which point at the newest model in each line. Responses always report the canonical id. An unknown id returns a 404 that suggests the closest match.

Retired models. Older models the providers have shut down or replaced (the o-series, GPT-5.3 and GPT-5.4 nano, Claude Haiku 4.5, Gemini 2.5, and earlier Gemini 3 Flash and preview releases) are no longer offered. A request naming one returns a 404 that names its replacement, for example o4-mini → gpt-5.6-terra; nothing is switched for you, since the replacement is priced differently.

Long prompts. Some models cost more per token when the prompt is long, exactly as the provider bills them: most GPT-5.4 and newer models above 272K input tokens, Gemini Pro above 200K, and Claude Haiku 5.5 above 100K. Once a prompt (cached tokens included) passes the threshold, the whole request is billed at that model's long-prompt rate, still at 50% of list. Those models are marked * below, and each model page lists both sets of rates.

Model idProviderIn /MOut /M
fable-5.2Anthropic$4.00$20.00
fable-5.1Anthropic$5.00$25.00
fable-5Anthropic$5.00$25.00
opus-5.5Anthropic$2.00$10.00
sonnet-5.5Anthropic$1.00$5.00
haiku-5.5 *Anthropic$0.05$0.25
opus-5Anthropic$2.50$12.50
sonnet-5Anthropic$1.00$5.00
opus-4.8Anthropic$2.50$12.50
opus-4.7Anthropic$2.50$12.50
opus-4.6Anthropic$2.50$12.50
sonnet-4.6Anthropic$1.50$7.50
gemini-4-carbonGoogle$1.00$5.00
gemini-4-argonGoogle$1.00$5.00
gemini-4-hydrogenGoogle$0.75$3.75
gemini-3.8-flashGoogle$0.375$1.875
gemini-3.6-flashGoogle$0.375$1.875
gemini-3.1-pro *Google$1.00$6.00
gemini-3.5-flash-liteGoogle$0.15$1.25
gpt-6.1-terra *OpenAI$0.50$2.50
gpt-6.1-sol *OpenAI$1.00$5.00
gpt-6-astra *OpenAI$5.00$25.00
gpt-6-sol *OpenAI$1.00$5.00
gpt-6-luna *OpenAI$0.05$0.25
chat-latestOpenAI$2.50$15.00
gpt-5.6-sol *OpenAI$2.00$10.00
gpt-5.6-terra *OpenAI$1.00$6.00
gpt-5.6-luna *OpenAI$0.10$0.60
gpt-5.5 *OpenAI$2.50$15.00
gpt-5.5-pro *OpenAI$15.00$90.00
gpt-5.4 *OpenAI$1.25$7.50
gpt-5.4-pro *OpenAI$15.00$90.00
gpt-5.4-miniOpenAI$0.375$2.25

Usage & cost

Every response carries a usage object. Costs are reported in USD at the Tokenless rate (50% of list) and drawn from your prepaid balance. Prompt-cache activity is broken out so you can see cache savings: Chat Completions and Messages report cache_read_input_tokens (cheaper cached reads) and cache_creation_input_tokens (writes), and Responses reports cached reads in input_tokens_details.cached_tokens. On Chat Completions, completion_tokens_details.reasoning_tokens shows how much of the output was thinking, which explains a short answer that still used many output tokens.

Cache writes bill at the provider's write price, at 50% of list like everything else. On Claude, a prompt marked "cache_control": { "type": "ephemeral", "ttl": "1h" } is written to the 1-hour cache at 2x the input price, while 5-minute writes cost 1.25x; Messages usage splits the two in cache_creation. GPT-6 and GPT-5.6 write to their cache automatically and bill those writes at OpenAI's write price. A request that may write to the cache places its hold at the write rate.

usage.json
{
  "prompt_tokens": 18,
  "completion_tokens": 224,
  "total_tokens": 242,
  "prompt_tokens_details": { "cached_tokens": 0 },
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "cost": 0.0028
}

Balance & billing

Tokenless is prepaid. Load a balance, and each request draws it down at the metered rate. Turn on auto-reload to recharge automatically when your balance gets low. If auto-reload is off and your balance reaches $0, API access pauses immediately: no overage, no debt.

Holds. Each request first places a short-lived hold on your balance for its worst-case cost (based on the output cap), then refunds the difference the moment we meter the actual tokens, so you're only ever charged for what you use. A request needs enough balance to cover that hold; if it doesn't, it's rejected with 402 before any tokens are spent. A lower max_tokens means a smaller hold, and images count toward it at a flat allowance of 5,000 tokens each rather than by file size. High reasoning levels raise max_tokens, so they hold more.

Failed requests are free. A request that fails to start (any error status) is never charged, and its hold is released right away. A stream cut off partway is charged for its prompt and the tokens generated before the cut, nothing more.

Errors & retries

Errors use each surface's native shape, so your SDK raises its usual typed exceptions. Chat Completions and Responses return OpenAI's envelope; the Messages API returns Anthropic's. Messages are written to be actionable: an invalid body names the offending field, and an unknown model suggests the closest id. Every response carries an X-Request-Id header; include it when you contact support and we can find the exact request.

error.json
// Chat Completions / Responses
{ "error": {
    "message": "Invalid request body: `messages.0.role`: Invalid enum value. ...",
    "type": "invalid_request_error",
    "code": "bad_request" } }

// Messages
{ "type": "error",
  "error": { "type": "overloaded_error", "message": "The model is overloaded right now. Please retry shortly." } }
StatusMeaningRetry?
400Invalid request: a malformed body, the wrong surface for the model, or a request the model rejected, such as a prompt over the context window (code context_length_exceeded).No, fix the request
401Missing or invalid API key.No
402Insufficient balance for this request's hold.After topping up
404Unknown model id, or an unknown endpoint (check that your base URL ends in /api/v1).No
413Request too large for the model.No
429Rate limited: slow down.Yes, after Retry-After
500Something went wrong on our side.Yes, with backoff
502Model temporarily unavailable.Yes, with backoff
503Model overloaded (the Messages API returns 529 overloaded_error).Yes, after Retry-After

Automatic retries

Before any output is sent, Tokenless retries brief provider hiccups (dropped connections, 5xx errors, momentary overload) with backoff, making up to three attempts, so most blips never reach you. A stream that has already started is never retried, because you already have part of the answer.

For anything that still gets through, retry 429, 500, 502, 503, and 529 with exponential backoff, waiting at least as long as the Retry-After header says. Don't retry other 4xx errors unchanged; they fail the same way every time. The official OpenAI and Anthropic SDKs already do this (two retries by default), so keep their built-in retries on:

retries.py
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenless.store/api/v1",
    api_key="sk-tk-...",
    max_retries=4,     # default is 2; agents and batch jobs benefit from more
    timeout=600,       # long reasoning turns can take minutes
)

Errors mid-stream

Once a stream has started, its HTTP status is already 200, so a later failure arrives as an event. The SDKs raise it as an exception:

  • Chat Completions: a data: {"error": {...}} event with code stream_interrupted, then [DONE]. No finish_reason is sent.
  • Messages: Anthropic's event: error, with type overloaded_error when the model is overloaded.
  • Responses: an error or response.failed event.

Retry the whole request when you see one. The interrupted attempt is charged only for what it used before the cut.

Ready to build?

Grab a key and make your first call in under a minute.