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.

Code	Meaning	Common Cause	Fix
`400`	Bad Request	Invalid request body, missing required fields	Check your request payload matches the API spec
`401`	Unauthorized	Invalid, revoked, or expired API key	Check key in dashboard, regenerate if needed
`402`	Payment Required	Subscription locked, or workspace/project/key budget exceeded	Update billing or increase budget in dashboard
`403`	Forbidden	Missing provider key, or routing policy blocked the request	Add provider key in Settings → Providers
`404`	Not Found	Model not found in TokenSense catalog	Check model name spelling, or use `/v1/models` to list available models
`409`	Conflict	Duplicate idempotency key in-flight	Wait for original request to complete
`429`	Too Many Requests	Rate limit exceeded (per-workspace, tiered by plan)	Slow down requests, check `Retry-After` header
`502`	Bad Gateway	Upstream provider error	Check provider status page, retry with backoff
`503`	Service Degraded	TokenSense temporary outage cap reached	Retry shortly — this is a temporary condition
`504`	Gateway Timeout	Provider took too long to respond	Reduce prompt size or try a faster model

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.

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.

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).

Using n8n? See the n8n Troubleshooting guide for n8n-specific error handling and retry configuration.

Error Codes Reference

Code	HTTP Status	Type	When
`INVALID_API_KEY`	401	authentication_error	API key is invalid or revoked
`API_KEY_EXPIRED`	401	authentication_error	API key has passed its expiration date
`PAYMENT_REQUIRED`	402	billing_error	Subscription is locked or canceled
`BUDGET_EXCEEDED`	402	billing_error	Workspace monthly budget exceeded
`PROJECT_BUDGET_EXCEEDED`	402	billing_error	Project monthly budget exceeded
`KEY_BUDGET_EXCEEDED`	402	billing_error	Per-key budget exceeded
`RATE_LIMITED`	429	rate_limit_error	Too many requests per minute
`INVALID_REQUEST`	400	invalid_request_error	Bad request body or missing fields
`MISSING_PROVIDER_KEY`	403	authorization_error	No API key for the target provider
`MODEL_NOT_FOUND`	404	invalid_request_error	Model not in TokenSense catalog
`POLICY_BLOCKED`	403	policy_error	Routing policy blocked the request
`SERVICE_DEGRADED`	503	server_error	Temporary outage cap reached
`PROVIDER_ERROR`	502	upstream_error	Upstream provider returned an error
`PROVIDER_TIMEOUT`	504	upstream_error	Provider took too long to respond
`IDEMPOTENCY_CONFLICT`	409	conflict_error	Duplicate request with same idempotency key in-flight