Error handling

/api/v1/chat/completions and /api/v1/models return errors in OpenAI format:

{
  "error": {
    "message": "Insufficient credits (balance: 0.00). Buy more credits or wait for your next billing cycle.",
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "param": null
  }
}

/api/v1/messages and /api/v1/messages/count_tokens return the Anthropic format:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Create one in your TokRouter settings."
  }
}

HTTP status codes

HTTP	code (OpenAI)	type (Anthropic)	Cause
400	invalid_request	invalid_request_error	Invalid JSON body, or missing model/messages
400	message_too_long	invalid_request_error	Message too long for the free tier
401	invalid_api_key	authentication_error	API key missing, invalid, or revoked
402	insufficient_credits	—	Credit balance exhausted (≤ 0)
403	subscription_required	—	Model reserved for subscribers or credit holders
404	model_not_found	not_found_error	Unknown or disabled model identifier
429	rate_limit_exceeded	rate_limit_error	Per-API-key rate limit exceeded
429	daily_limit_reached	invalid_request_error	Free-tier daily limit reached
502	upstream_auth_error	api_error	Server-side configuration error on TokRouter's end (not your key)
provider-dependent	upstream_error	api_error	The model provider returned an error; the HTTP code passed through is theirs

What never happens

• A failed request never charges your credits: billing only happens after a successful response containing the exact usage (see Credits and billing).
• A 401/403 error from the model provider (misconfiguration on TokRouter's side) is never presented to you as a problem with your API key: it always returns 502 with upstream_auth_error / api_error.
• There is no automatic fallback to another model yet when a provider errors: the request simply fails with the code above.

Rate limiting

Every response (success or error) includes the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. A 429 error also adds Retry-After (seconds until the next window).