Error Codes

When a request through TokenSense fails, you'll receive one of these HTTP status codes with a structured error body. This page explains what each one means and how to fix it.

Structured Error Body

Every error response from TokenSense uses a standard envelope with a machine-readable code field. This makes it easy to handle errors programmatically in n8n, Make, Zapier, or custom integrations.

{
  "error": {
    "code": "BUDGET_EXCEEDED",
    "message": "Monthly workspace budget exceeded.",
    "type": "billing_error",
    "budget_usd": 50.00,
    "spent_usd": 51.23
  }
}

The code field is always a constant string you can match on. The type groups related errors (e.g. all billing errors share "billing_error"). Extra fields like budget_usd are included when relevant.

Budget Verification Failures (503)

A budget block and a budget check failure are different things, and TokenSense reports them differently. If we cannot read your budget, you get a 503 — never a 402.

{
  "error": {
    "code": "BUDGET_CHECK_UNAVAILABLE",
    "error_class": "budget_check_unavailable",
    "message": "Budget verification is temporarily unavailable. This is not a billing decision — retry shortly.",
    "type": "service_unavailable",
    "retryable": true,
    "retry_after_seconds": 5,
    "scope": "project"
  }
}

Branch on error_class === "budget_check_unavailable" (or simply on status === 503) and retry with backoff, honouring Retry-After. The scope field tells you which budget layer could not be read: workspace, project, workflow, or key.

Rate Limits vs Budget Blocks

TokenSense uses different HTTP status codes for rate limits and budget blocks so your automations can handle them correctly:

• 429 (Too Many Requests) — you're sending requests too fast. Check the Retry-After header and wait before retrying. Rate limits are per-workspace and tiered by plan: Starter 30/min, Pro 120/min, Agency 300/min.
• 402 (Payment Required) — a budget cap has been hit (workspace, project, or per-key). Do not retry — increase the budget in your dashboard or upgrade your plan. A 402 always carries a non-null budget_usd and a spent_usd at or above it: we only ever say "budget exceeded" when we have actually measured both.
• 503 with BUDGET_CHECK_UNAVAILABLE — we could not read your budget (for example, a temporarily degraded database). Your request was not forwarded and you were not charged, but this is an infrastructure condition, not a billing one. Retry after the Retry-After header. Never open a circuit or stop a workflow on it.

400 — Bad Request

The request body is invalid or missing required fields. Check that your payload matches the expected format for the endpoint you're calling.

401 — Unauthorized

Your request is missing the Authorizationheader or the API key is invalid/expired. Go to your dashboard, check that the key exists and hasn't been revoked. If in doubt, regenerate the key and update your workflow configuration.

402 — Payment Required

Your subscription needs attention or a budget cap has been reached. Error codes: PAYMENT_REQUIRED (subscription locked), BUDGET_EXCEEDED (workspace budget), PROJECT_BUDGET_EXCEEDED (project budget), KEY_BUDGET_EXCEEDED (per-key budget). Check your billing status and budget settings in the dashboard.

403 — Forbidden

TokenSense understood the request but can't forward it. Error codes: MISSING_PROVIDER_KEY (no API key configured for the provider), POLICY_BLOCKED (a routing policy blocked the request). Go to Settings → Providers and add the missing key, or review your routing policies.

429 — Too Many Requests

Rate limit exceeded. The limit is per workspace (not per API key) and tiered by plan. The response includes a Retry-After header indicating how long to wait. Also check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response to monitor your usage proactively.

502 — Bad Gateway

The upstream provider (OpenAI, Anthropic, Google) returned an error. This is usually a temporary issue on the provider's side. Check the provider's status page and retry the request with exponential backoff. If the error persists, try a different model or provider.

504 — Gateway Timeout

The upstream provider took too long to respond. This can happen with large prompts, long context windows, or reasoning models that take extended time. Try reducing the prompt size, using a shorter context, or switching to a faster model (e.g., Flash or Mini variants).

Error Codes Reference

Related

• API Reference
• Budgets & Spend Caps
• n8n Troubleshooting