# Costs and limits
Plan in EUR, bound each request and distinguish missing usage from zero cost.

## Read current prices
The [catalog](https://tokenlane.de/models) publishes model and route prices with their units and currency. Model-wide prices are aggregates; the chosen route, request fees, cached tokens and conditional pricing can change the actual charge. Keep decimal amounts as exact strings in accounting code.

## Bound a request
Use `max_tokens` for output, observe the model's context limit and set a client timeout. A timeout is not proof that no provider work or charge occurred. Cancel requests your application no longer needs.

### curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}'
```

### node

```node
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}, {});
console.log(response);
```

### python

```python
import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}''')
response = client.chat.completions.create(
    model=body["model"],
    messages=body["messages"],
    max_tokens=body["max_tokens"]
)
print(response)
```

### vercel

```vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
  model: tokenlane("deepseek/deepseek-v4-flash-0731"),
  messages: [
  {
    "role": "user",
    "content": "Hello"
  }
],
  maxOutputTokens: 400,
});
console.log(result.text);
```

## Account for additional work
OCR, server tools and PII detection can add separately reported cost details. Do not add a detail again when it is already included in the reported total. When token usage or a total is unavailable, preserve that absence instead of inventing zero. Reasoning and caching follow the selected route's prices.

## Respond to limits
| Error | What to do |
|---|---|
| 429 | Respect `Retry-After` and use bounded backoff with jitter |
| Context or body size | Reduce the input before retrying |
| Key budget or credit | Check the organization balance, shared workspace budget and key policy |

Changing a request cannot relax a stricter existing limit.

## Customer tiers

The operator-managed tier catalog sets these capacity ceilings per organization, shared across its keys:

| Tier | Concurrent requests | Requests per minute (RPM) | Tokens per minute (TPM) | Spend per rolling 24 h / UTC calendar month (EUR) |
|---|---:|---:|---:|---:|
| T0 | 4 | 30 | 100,000 | 0 / 0 |
| T1 | 8 | 60 | 200,000 | 25 / 100 |
| T2 | 32 | 300 | 1,000,000 | 250 / 1,000 |
| T3 | 64 | 1,000 | 4,000,000 | 1,000 / 5,000 |

New organizations start in **T0 and remain blocked pending operator review** (`operator_review`); its catalog numbers do not permit inference. Legal or identity review can also suspend other tiers. A tier change is not a way to bypass review.

These are ceilings, not guaranteed throughput. Stricter organization and key policies still apply, and provider capacity can impose additional limits. TPM admission includes reservations for pending work.

An exhausted tier capacity returns `429 rate_limited`; respect `Retry-After`, reduce concurrency or request size, or ask support for a tier review.

Spending limits are separate from capacity and remain unchanged:

- The same spending ceilings also apply to the verified customer identity across all its organizations.
- The maximum reservation per request remains EUR 0 in T0, EUR 2 in T1 and EUR 10 in T2/T3.
- Credit, workspace and key restrictions can be stricter.

A spending risk ceiling returns `403 permission_denied`, not a capacity 429; the message and remedy hint distinguish the per-request reservation ceiling from rolling or monthly spending ceilings.

## Distinguish spending restrictions

Before paid upstream work the gateway reserves an estimate, including configured fees and media charges. 

| Limit | Error |
|---|---|
| Organization credit, key limit | `402 insufficient_credits` |
| Shared workspace budget | `402 workspace_budget_exceeded` |

Concurrent requests reserve against the same remaining funds. Workspace `limit` and `limit_reset` apply across its keys; the organization uses its prepaid balance, not a second policy spending limit.

## Your own provider keys
Requests that use your own provider keys or endpoints (BYOK) never pay the model price to Tokenlane; the provider bills you directly. Tokenlane charges a service fee instead. Each verified customer identity has a monthly allowance per UTC calendar month, shared by all of its organizations and by keys and endpoints together. The current fee and allowance are shown under [Provider keys](https://tokenlane.de/settings/provider-keys). Organization administrators receive an email at 80 % and at 100 % of the allowance.

After the allowance every request pays the fee per token (input and output together) from your Tokenlane credit, independent of the model and of any price you enter for your own endpoint. The month's fee tokens are billed in whole blocks of 1,000; the remainder is never charged, so you never pay for a partial block.

How fee tokens are counted:

- **Curated providers:** the validated provider usage counts.
- **Endpoints you define:** Tokenlane measures request and response itself with a fixed rule: one token per four UTF-8 bytes of text, plus 1,000 tokens per image, 2,000 per audio or file part and 5,000 per video part. What your endpoint reports or charges does not change the fee.

A request that returns nothing (failed or refused) costs nothing; an aborted stream is measured by what had arrived.

Before a request beyond the allowance starts, the maximum fee is reserved. If your credit cannot cover it, the gateway answers `402 insufficient_credits` with a hint, and the request does not count against the allowance. The activity details and `GET /v1/generation` report the fee, this request’s ordinal and the monthly allowance, plus reported and estimated tokens, separately as `byok_fee`. This is request-time metadata, not a live identity-wide remaining allowance in the credits page.