tokenflow

Reference

API errors

When the gateway rejects or cannot complete a request, it answers with a JSON problem object (RFC 9457). The type field links to the entry on this page.

HTTP 429
{
  "type": "https://tokenflow.dev/problems/quota_exceeded",
  "title": "quota_exceeded",
  "status": 429,
  "code": "quota_exceeded",
  "detail": "monthly token quota of … is used up until …",
  "retryable": false
}

Errors with "retryable": true are safe to retry; honour the Retry-After header when it is present.

invalid_json 400

The request body is not a JSON object.

What to do: Send a JSON object as the body, with Content-Type: application/json.

missing_model 400

The request does not name a model.

What to do: Set the model field, for example qwen3.8-27b.

invalid_model 400

The model name is longer than the gateway accepts.

What to do: Use a model ID from GET /v1/models.

media_not_allowed 400

The request carries media the gateway does not accept: more than 16 images, an image over its size or pixel limit, a remote URL, video, or a media-processing override.

What to do: Send at most 16 inline PNG, JPEG, WebP or GIF images and trim older screenshots from the history. The detail field says which limit was hit.

invalid_request 400

The console playground can’t send this conversation. It sends at most 100 messages, with text and inline images only (no tools or remote image links).

What to do: Clear the chat or shorten it. Use the API for tools.

unauthorized 401

The API key is missing, unknown or revoked, or its organization is disabled.

What to do: Send your key as Authorization: Bearer or x-api-key. If it still fails, write to support.

tenant_disabled 403

The console playground can’t act for this organization because it is disabled.

What to do: Write to support.

model_not_found 404

No model with this name exists for your key.

What to do: Pick a model from GET /v1/models.

not_found 404

The path or method is not part of the API.

What to do: Use /v1/chat/completions, /v1/completions, /v1/responses, /v1/messages or GET /v1/models.

request_too_large 413

The request body is over the size limit (12 MiB) or the images inside it are too large.

What to do: Send fewer or smaller images, or a shorter history.

quota_exceeded 429

Your organization has used its monthly token quota.

What to do: The detail field says when the quota resets. Write to support to raise it.

rate_limited 429

Too many requests with unknown keys came from your address.

What to do: Wait for the time in the Retry-After header and check that your key is correct.

client_closed 499

Your client closed the connection before the response finished.

What to do: Nothing to fix on our side. Tokens already sent are billed.

upstream_failed 502

Every node that could serve the model failed before the response started.

What to do: Retry after the time in Retry-After. Quote x-tokenflow-request-id if you contact support.

control_unavailable 503

The gateway could not read its routing state for a moment.

What to do: Retry after the time in Retry-After.

no_serving_node 503

No node is currently serving this model for your organization.

What to do: Retry after the time in Retry-After. If it lasts, write to support.