Error Codes

Complete reference of error codes returned by the FirstRouter API

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "error": {
    "message": "Current Key Invalid",
    "type": "invalid_params"
  }
}

Error Codes Reference

invalid_params

400 Bad Request

Description

The request parameters are invalid or missing required fields.

Solution

Check your request parameters and ensure all required fields are provided with correct data types.

authentication_failed

401 Unauthorized

Description

The API key is invalid or missing.

Solution

Verify your API key is correct and included in the Authorization header.

user_banned

403 Forbidden

Description

Your account has been suspended or banned.

Solution

Contact support to resolve account suspension issues.

system_error

500 Internal Server Error

Description

An internal server error occurred.

Solution

Retry your request. If the issue persists, contact support.

rate_limit_exceeded

429 Too Many Requests

Description

You have exceeded the rate limit for API requests.

Solution

Reduce your request rate and implement exponential backoff retry logic.

model_not_found

404 Not Found

Description

The specified model does not exist or is not available.

Solution

Check the model ID and ensure it's available in your region.

insufficient_quota

402 Payment Required

Description

Your account does not have enough credits to complete this request.

Solution

Add more credits to your account or upgrade your plan.

channel_unavailable

503 Service Unavailable

Description

The requested model provider is temporarily unavailable.

Solution

Try a different model or retry later when the provider is available.

request_timeout

408 Request Timeout

Description

The request took too long to process and timed out.

Solution

Reduce the complexity of your request or try again later.

token_expired

401 Unauthorized

Description

Your API token has expired.

Solution

Generate a new API key from your dashboard.

invalid_model

400 Bad Request

Description

The specified model is not supported for this operation.

Solution

Use a supported model for this type of request.

content_filtered

400 Bad Request

Description

The request or response content was filtered due to policy violations.

Solution

Modify your request to comply with content policies.

service_overloaded

503 Service Unavailable

Description

The service is currently experiencing high load.

Solution

Implement retry logic with exponential backoff.

invalid_api_key

400 Bad Request

Description

The provided API key format is invalid.

Solution

Ensure your API key is correctly formatted and valid.

channel_disabled

503 Service Unavailable

Description

The requested model provider has been disabled.

Solution

Use an alternative model from a different provider.

upstream_provider_error

502 Bad Gateway

Description

An error occurred with the upstream model provider.

Solution

Retry your request or try a different model provider.

Handling Errors

Best Practices

  • Always check the HTTP status code and error type
  • Implement exponential backoff for retryable errors
  • Log errors for debugging and monitoring
  • Handle different error types appropriately in your application

Retryable Errors

The following errors are typically temporary and can be retried:

  • rate_limit_exceeded - Wait and retry with exponential backoff
  • system_error - Retry after a short delay
  • service_overloaded - Retry with exponential backoff
  • channel_unavailable - Try different model or retry later
  • request_timeout - Retry with potentially simpler request
  • upstream_provider_error - Retry or try different provider

Non-Retryable Errors

The following errors require action before retrying:

  • authentication_failed - Fix API key
  • invalid_params - Fix request parameters
  • insufficient_quota - Add more credits
  • user_banned - Contact support
  • content_filtered - Modify request content