Error Codes - Requesty Docs

When a request fails, Requesty returns a standard JSON error response with an HTTP status code and a human-readable message. Errors originate from either the router (Requesty’s own validation and routing logic) or an upstream provider (OpenAI, Anthropic, Google, etc.).

Example error response (HTTP 404)

{
  "error": {
    "origin": "router",
    "message": "Provider and/or model not supported"
  }
}

The origin field tells you where the error came from — "router" means Requesty caught the problem before it reached a provider, while "provider" means an upstream LLM provider returned the error.

Authentication & Authorization

Errors related to API key validation, account status, and access control.

HTTP Code	Origin	Error Message	Description	What to Do
401	`router`	Unauthorized	No `Authorization` header was provided, or it is empty.	Include `Authorization: Bearer sk-...` in your request headers.
402	`router`	Insufficient balance, top up at: https://app.requesty.ai/settings	Your organization’s balance has been exhausted.	Top up your balance or contact your organization admin.
403	`router`	Invalid authorization token	The API key is invalid, expired, or revoked.	Generate a new API key at app.requesty.ai/api-keys.
403	`router`	Your account has been restricted…	Your organization has been restricted due to a policy violation.	Contact [email protected] for more information.
403	`router`	Provider blocked by policy	The requested model is not in the approved models or access list for your API key.	Ask your admin to add the model to your access list, or use an approved model.
412	`router`	Reached monthly spend limit for API key	The monthly spending cap for your API key or project has been reached.	Wait for the next billing cycle, or ask your admin to increase the spend limit.

Request Validation

Errors returned when the request payload is malformed or contains invalid parameters.

HTTP Code	Origin	Error Message	Description	What to Do
400	`router`	Invalid request format	The request body is malformed, missing required fields, or contains invalid JSON.	Check your request body against the API reference. Ensure valid JSON and required fields like `model` and `messages`.
400	`router`	Request body is empty	An empty request body was sent.	Provide a valid JSON request body.
400	`router`	Invalid model, expected: “provider/model”	The `model` field is not in the required `provider/model` format.	Use the format `provider/model` (e.g., `openai/gpt-4.1`, `anthropic/claude-sonnet-4-5`). See available models.
400	`router`	Invalid model params	Model parameters (region, reasoning effort, etc.) are invalid.	Check supported model parameters and region suffixes.

Model & Routing

Errors related to model resolution, routing policies, and plan compilation.

HTTP Code	Origin	Error Message	Description	What to Do
404	`router`	Provider and/or model not supported	The requested provider/model combination does not exist in Requesty’s model library.	Check the model library for available models. Verify the provider and model names are spelled correctly.
400	`router`	Routing policy is unknown	The referenced routing policy does not exist.	Verify the policy name in your `model` field (e.g., `policy/my-policy`). Create or check policies at Routing Policies.
422	`router`	Routing policy uses forbidden models or BYOK is missing	All models in the routing policy are either not in your access list, or require BYOK credentials that haven’t been configured.	Add the policy’s models to your access list, or configure the required BYOK provider keys.
500	`router`	Routing policy is corrupted	The routing policy exists but failed to compile into a valid plan.	Re-create the routing policy, or contact support if the issue persists.
500	`router`	Smart routing failed	The smart routing classifier was unable to select a model.	Retry the request. If persistent, fall back to a specific model or policy.

Provider Errors

Errors originating from upstream providers (OpenAI, Anthropic, Google, Bedrock, etc.), translated and normalized by Requesty.

HTTP Code	Origin	Error Message	Description	What to Do
429	`provider`	Too many requests	The upstream provider returned a rate limit error.	Reduce request frequency, or create a Routing Policy to automatically failover to another provider.
502	`provider`	Provider is down: Bad Gateway	The upstream provider returned a 502 error.	Retry after a short delay. Consider setting up a Fallback Policy for automatic failover.
502	`router`	There was a problem with the provider stream	The provider sent an error within an SSE stream after streaming had started.	Retry the request. If consistent, try a different provider or model.
503	`router`	The provider timed out, please try again	The upstream provider did not respond within the timeout window.	Retry the request. For long-running requests, consider models with higher timeout allowances or use a fallback policy.
424	`router`	Invalid provider response format	The provider returned a response that Requesty could not parse.	Retry the request. This is typically a transient provider issue. If persistent, contact support.
424	`router`	Provider response missing usage	The provider did not include token usage data in the response.	Retry the request. This is a transient provider issue.
529	`provider`	The provider is overloaded, please try again	The upstream provider is experiencing high load (common with Anthropic).	Wait and retry, or use a fallback policy to route to an alternative provider automatically.
504	`provider`	Provider is down: Gateway timeout	The upstream provider returned a 504 Gateway Timeout.	Retry after a short delay. Set up automatic failover with a Routing Policy.

Requesty automatically retries provider errors when you use a Routing Policy with multiple models. Provider rate limits (429), overload (529), timeouts (503), and bad gateway (502) errors all trigger automatic fallback to the next model in the chain.

Rate Limiting

HTTP Code	Origin	Error Message	Description	What to Do
429	`provider`	Too many requests	Upstream provider rate limit.	See Provider Errors above.
429	`router`	Too many simultaneous requests for user	Your API key has exceeded the configured concurrent request limit.	Reduce parallelism, or ask your admin to increase the in-flight rate limit for your project.

Security & Guardrails

HTTP Code	Origin	Error Message	Description	What to Do
403	`router`	Provider blocked by policy	The requested model is blocked by your organization’s routing policy.	Use a model that is allowed by your policy, or ask your admin to update the policy.
400	`router`	Request security policy not found	A guardrail policy referenced in your configuration does not exist.	Verify guardrail configuration in the Requesty dashboard.
400	`router`	Request violated security policy	The request content triggered a guardrail violation with the `block` action.	Review and adjust your request content, or update guardrail settings if this is a false positive.

Connection & Client Errors

HTTP Code	Origin	Error Message	Description	What to Do
499	`router`	Client closed connection	The client disconnected before the response completed.	Ensure your HTTP client has a sufficient timeout. For streaming requests, keep the connection open until the stream ends.
499	`router`	Stream interrupted, please try again	The streaming response was interrupted after some data was already sent.	Retry the request. Ensure a stable network connection.

Internal Errors

HTTP Code	Origin	Error Message	Description	What to Do
500	`router`	Internal server error	An unexpected error occurred within the router.	Retry the request. If persistent, contact [email protected] with your request ID.
500	`router`	Get API key configuration failed	Requesty failed to load the configuration for your API key.	Retry the request. If persistent, this may indicate a temporary platform issue.
500	`router`	Apply rate-limit failed	The rate-limiting system encountered an internal error.	Retry the request. This is a transient infrastructure issue.

Context Length Errors

When your input exceeds a model’s context window, Requesty translates the provider-specific error into a clear, actionable message.

HTTP Code	Origin	Error Message	What to Do
400	`router`	Your input is tokens, which exceeds the model’s maximum context length of tokens.	Reduce your input by shortening messages, removing older conversation history, or summarizing prior context.
400	`router`	Your input is tokens and max_tokens is , which together exceed the model’s context limit of tokens.	Lower `max_tokens` or shorten your input so that `input + max_tokens` stays within the model’s context window.
400	`router`	Your input exceeds the model’s maximum context length.	Shorten your messages. See the model library for each model’s context window.
400	`router`	max_tokens must be greater than thinking.budget_tokens.	Increase `max_tokens` or decrease `thinking.budget_tokens` in your request.

Error Response Format

All errors return JSON with the following structure:

{
  "error": {
    "origin": "router",
    "message": "Human-readable error description"
  }
}

Field	Type	Description
`error.origin`	`string`	Where the error originated — `"router"` for Requesty errors, `"provider"` for upstream provider errors.
`error.message`	`string`	A human-readable description of the error.

The HTTP status code is returned in the response status line (e.g., HTTP/2 404). The origin field helps you determine whether to fix your request (router) or retry / failover (provider).

Router error (your request)
Provider error (upstream)

HTTP 400

{
  "error": {
    "origin": "router",
    "message": "Invalid model, expected: \"provider/model\""
  }
}

HTTP 529

{
  "error": {
    "origin": "provider",
    "message": "The provider is overloaded, please try again"
  }
}

Best Practices

Use Routing Policies

Set up fallback chains so provider errors (429, 502, 503, 529) automatically retry on a different model — your application never sees the error.

Set Spend Limits

Configure per-project or per-key spend limits to avoid unexpected 402 errors from balance exhaustion.

Monitor with Logs

Use the Logs view to inspect individual request errors, filter by status code, and debug issues in real time.

Check the Model Library

Verify model names, providers, and capabilities before making requests to avoid 404 and 400 errors.

Track errors in Advanced Analytics. Group by status_code in Advanced Analytics to see which errors are costing you the most and spot trends over time.

Include request IDs in support tickets. Every response includes an x-request-id header. When contacting support, include this ID so we can trace the exact request path through the router.

Error Recovery and Retry Strategy

Implement exponential backoff with jitter for retryable errors. The following strategy works for all Requesty API calls:

import time
import random

def call_with_retry(fn, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries + 1):
        try:
            return fn()
        except Exception as e:
            status = getattr(e, 'status_code', 0)
            # Retry on 429, 502, 503, 529 only
            if status not in (429, 502, 503, 529) or attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            retry_after = getattr(e, 'headers', {}).get('Retry-After')
            if retry_after:
                delay = max(delay, float(retry_after))
            time.sleep(delay)

Error	Retryable	Strategy
400	No	Fix request payload
401/403	No	Fix credentials or permissions
402	No	Top up account balance
429	Yes	Respect `Retry-After` header, exponential backoff
502/503	Yes	Retry with backoff, or use a routing policy for automatic failover
529	Yes	Provider overloaded, retry with backoff
500	Maybe	Retry once, then contact support if persistent

Use routing policies for automatic recovery. Instead of implementing retry logic in your application, create a routing policy with multiple models. Requesty automatically retries on provider errors (429, 502, 503, 529) using the next model in your fallback chain.

​Authentication & Authorization

​Request Validation

​Model & Routing

​Provider Errors

​Rate Limiting

​Security & Guardrails

​Connection & Client Errors

​Internal Errors

​Context Length Errors

​Error Response Format

​Best Practices

Use Routing Policies

Set Spend Limits

Monitor with Logs

Check the Model Library

​Error Recovery and Retry Strategy

Authentication & Authorization

Request Validation

Model & Routing

Provider Errors

Rate Limiting

Security & Guardrails

Connection & Client Errors

Internal Errors

Context Length Errors

Error Response Format

Best Practices

Error Recovery and Retry Strategy