Choosing a TokenLab Delivery Tier: Auto, Verified, or Official

A request can fail with a 503 even though the model ID is perfectly valid, and the cause is often the delivery tier you pinned. In our pipeline we hit this when we forced one option on a model that did not offer it. This guide explains the three delivery tier options, the order in which settings apply, and what each one means for your bill. All facts below come from TokenLab documentation and the live model API, observed 2026-10-03.

Key Takeaways

The three delivery tier options

The API reference (observed 2026-10-03) defines three options:

• Auto uses TokenLab Verified when available, then Official if needed. You pay for the option that completes your request.
• TokenLab Verified is delivery verified by TokenLab. TokenLab prices apply.
• Official is based on the model maker's public price. The price shown on TokenLab is what you pay.

Generation requests accept the header X-TokenLab-Delivery-Policy: auto | verified | official. An invalid header value returns 400.

Which setting applies first

Three places can set the delivery tier. The documented order is:

1. The request header.
2. The API key setting.
3. The Workspace default.

The header overrides the key, and the key overrides the Workspace. Realtime sessions are the exception: they use the API key or Workspace setting and do not accept a query-string override.

Set the delivery tier on a request

Here is a Chat Completions call that pins Official delivery. The model ID claude-sonnet-5 is listed in the live model API with both options available. See the model page.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

The same header works on the Anthropic Messages endpoint. For /v1/messages the key header can be x-api-key, which the API reference says Anthropic Messages accepts.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Set the delivery tier on an API key

To make a delivery tier the default for one key, use the Management API with a management token (mt-...). The Create API Key and Update API Key pages (both observed 2026-10-03) document a deliveryPolicy field. Its values are auto, verified, official, or null. A null value inherits the Workspace policy.

This sketch follows the documented PATCH shape. The key ID is the docs example value.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

Update requires at least one field, so this body is valid on its own. Responses report the setting as delivery_policy, where null means the key inherits the Workspace default. The create endpoint accepts the same deliveryPolicy field in its request body. Omitting it on create is consistent with the documented null inheritance, as the create example response shows delivery_policy: null.

When the requested option is unavailable

If the option you request has no supply, TokenLab returns 503 delivery_tier_unavailable and a request ID. The error handling guide (observed 2026-10-03) explains how to read retryable.

A 5xx status does not always mean a temporary outage. When the selected operation has no supply in that tier, retryable is false and retry_after is omitted. Do not repeat the same request unchanged. Instead:

1. Read code and retryable, not the human-readable message.
2. Save the Request ID from the response headers.
3. Check the model's delivery availability with GET /v1/models before choosing another model or tier.

The guide warns that similar model names do not prove availability. A client should branch on code, and retry a 5xx only when retryable is true, respecting retry_after and capping attempts.

Check which options a model has

The model endpoint reports delivery availability by option. These values come from the live model API, observed 2026-10-03:

Model ID	Verified	Official	Model page
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

For example, pinning verified on deepseek-v4-flash is the kind of request that would hit delivery_tier_unavailable, because the API reports no Verified supply today. Official and Auto remain valid there.

Check any model yourself:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

Availability is checked when each request runs, and the Billing guide says delivery labels describe supported options. Treat the model API as a snapshot and re-read it before you hard-code a pinned tier.

How the choice affects what you pay

The Billing guide (observed 2026-10-03) says each completed request is charged once, for the option that produced the result:

• TokenLab Verified uses TokenLab public prices.
• Official uses the Official price layer based on the model maker's public price.
• Auto charges whichever option completes the request.

For paid generation, Console shows a maximum estimate before confirmation, and Usage shows the final charge. Any unused reserved amount is released. On the Models page, a dash in the TokenLab price column means no Verified offer is currently available. It does not mean free.

The guide documents no fixed price gap between Verified and Official, so we will not claim one. For the live TokenLab price on claude-sonnet-5, the model API lists input at 0.9 USD and output at 4.5 USD per 1M tokens (pricing updated 2026-10-02). As an estimate, 100,000 input tokens plus 10,000 output tokens is 0.09 + 0.045 = 0.135 USD. That figure uses the listed TokenLab price only. Read the Official price on the model page before comparing.

A short decision guide

• Default to Auto when you want the request to complete and can accept either price layer.
• Pin Verified when you need TokenLab prices and the model reports verified: true.
• Pin Official when you need the model maker's public price basis, or when the model has no Verified supply.
• Set the key default for workers that always need the same tier, and use the header for one-off exceptions.

Before pinning, read GET /v1/models/{model}. Run a small test and confirm the charge in Usage.

Next step: create a key with a delivery policy

Create an API key in the Console, or call POST /v1/management/api-keys with a management token and set deliveryPolicy in the body, as described in the Create API Key page. Then send one small request with the header from above and check the charge in Usage.

FAQ

Which setting wins if the header, API key, and Workspace disagree?

The request header wins. The API key setting overrides the Workspace default. Realtime sessions skip the header and use the key or Workspace setting.

Why did I get 503 delivery_tier_unavailable, and should I retry?

The tier you requested has no supply for that operation. Read retryable: when it is false, do not resend the same request. Check availability with GET /v1/models and change the tier or model.

Does Official cost more than TokenLab Verified?

The docs do not state a fixed difference. Verified uses TokenLab public prices, and Official uses the model maker's public price basis. Compare the two on the model page and confirm the final charge in Usage.

How do I see which delivery options a model supports?

Call GET /v1/models/{model}, which needs no key. Today claude-sonnet-5 and gpt-5.6-terra report Verified and Official, while deepseek-v4-flash reports Official only.

Can I set a delivery option for Realtime sessions?

Yes, through the API key or Workspace setting. Realtime sessions do not accept a query-string override.

Create your TokenLab API key in the Console