Errors, limits and credits

Every error has the same nested shape. Messages also includes its required outer type: error marker.

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "field.path",
    "code": "unsupported_parameter",
    "retryable": false
  }
}

• 400: malformed or unsupported request
• 401: rail key invalid or revoked
• 402: monthly spend cap reached, or managed credits exhausted
• 403: model blocked by your admin's allowlist, or no provider key connected
• 404: unknown model or API route
• 405: wrong method for a known route
• 409: idempotency conflict; inspect the original request ID
• 429: TokenSpend rate limit, with accurate Retry-After and rate-limit headers
• 5xx: TokenSpend or model service failure

retryable marks a potentially transient failure, not a guarantee. Honor Retry-After; otherwise use bounded backoff with jitter. Do not retry an unchanged 4xx request blindly.

unsupported_parameter

Check error.param against the model and protocol contract. Remove the unsupported field.

model_not_found

Copy a canonical ID from GET /v1/models. Do not use a client-specific alias.

idempotency_already_completed

Inspect the receipt identified by the response header. The original body is not replayed.

tokenspend_rate_limit_exceeded

Wait for Retry-After. Workspace limits are shared across its keys.

upstream_rate_limited

Retry with bounded backoff. This is a model-service limit, not your TokenSpend quota.

upstream_schema_violation

Invalid model output was withheld. A new attempt can incur another charge; keep the failed receipt.

reasoning_output_exhausted

Increase the output budget within the model limit. Reasoning can consume the budget before visible text.

If a model fails after a stream opens, Chat Completions and Messages emit a protocol error with the same stable code. Responses emits response.failed. Raw model service errors are not forwarded.

The current baseline is 100 requests per minute at both workspace and rail-key scope, with separate burst protection. Limits are shared across server instances. A 429 returns tokenspend_rate_limit_exceeded, Retry-After, limit, remaining, and reset headers.

Upstream throttling is a retryable 503 with upstream_rate_limited. It is never presented as a TokenSpend limit. Request a higher-limit trial.

The burst baseline is 100 requests per 1 second at each scope. Approved temporary overrides can differ. Read x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset (Unix seconds) on responses. The scope and policy headers identify the limiting bucket.

BYOK routing is free; usage is billed by your provider. Managed requests use your TokenSpend balance at the published model rate. A 5% fee applies when buying credits, not to token rates.

One-time top-ups start at $5. Add credits in Router. Auto top-up can recharge credits from a saved card when the balance drops below a threshold you set on the credits page. A successful payment must finish processing before the balance updates.

A 402 can mean insufficient credits or a workspace spend cap. An admin should check both before retrying. Failed or interrupted generations may still have billable usage; the receipt preserves its metering state. Current terms do not specify a credit refund policy. Contact support before purchase if you need refund terms.

TokenSpend does not store Router prompts or responses. Requests pass through in memory only to forward them and return the reply. There is no request logging option.

Bodies are never written to operational logs. Receipts carry metadata only: engineer, model, token counts, latency, status and list-price cost. Fleet capture is unaffected by any of this: the hook sends token counts, timestamps and git refs, never code.

See the privacy notice for data handling and deletion requests.

TokenSpend does not currently offer provider ZDR. Provider retention is separate. See the route boundary for BYOK and managed traffic.

Any existing downstream handling requirement remains enforced. Hiding its dashboard control does not weaken it. Required routes need current evidence for the actual account, model, endpoint, and request features. Unknown, expired, revoked, or incompatible evidence cannot qualify.

API status updates from scheduled probes. The current schedule is daily. Uptime is the share of successful recorded checks, not continuous coverage or an SLA. Check the observation time and stale or limited-history labels before relying on it.

GET /v1/health is a lightweight health check, not proof that every model can generate. Routing retries and configured fallback reduce some failures; they do not guarantee availability.

Contact support with the request ID, UTC time, model, client version, and safe error code. Never send credentials or private content.