Errors

Edgee uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication failed, etc.). Codes in the 5xx range indicate an error with Edgee’s servers. When an error occurs, the API returns a JSON object with an error field containing details about what went wrong.

Error Response Format

object

required

The error object.

string

required

A machine-readable error code that briefly explains the error reported.

string

required

A human-readable message providing more details about the error.

{
  "error": {
    "code": "bad_model_id",
    "message": "Invalid model ID: 'invalid-model'"
  }
}

HTTP Status Code Summary

Below is a summary of the HTTP status codes that Edgee API uses.

HTTP Code	Status	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter, invalid model ID, model not found, or provider not supported.
401	Unauthorized	No valid API key provided, or the Authorization header is missing or malformed.
403	Forbidden	The API key doesn’t have permissions to perform the request. This can occur if the key is inactive, expired, or the requested model is not allowed for this key.
404	Not Found	The requested resource doesn’t exist.
429	Too Many Requests	Provider rate limit or usage limit exceeded. Identify which limit applies before retrying.
500, 502, 503, 504	Server Errors	Something went wrong on Edgee’s end. (These are rare.)

Error Codes

400 Bad Request

string

One of the following error codes:

bad_model_id: The model ID format is invalid
model_not_found: The requested model does not exist or is not available
provider_not_supported: The requested provider is not supported for the specified model
streaming_not_supported: Streaming is only supported when using Anthropic provider for Messages API

{
  "error": {
    "code": "bad_model_id",
    "message": "Invalid model ID: 'invalid-model'"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Model 'openai/gpt-1' not found"
  }
}

{
  "error": {
    "code": "provider_not_supported",
    "message": "Provider 'anthropic' is not supported for model 'openai/gpt-5.2'"
  }
}

{
  "error": {
    "code": "streaming_not_supported",
    "message": "Streaming for Messages API is only supported when the model uses the Anthropic provider"
  }
}

401 Unauthorized

string

Always "unauthorized".

{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid Authorization header format"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Failed to retrieve API key: <error details>"
  }
}

403 Forbidden

string

Always "forbidden".

{
  "error": {
    "code": "forbidden",
    "message": "API key is inactive"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "API key has expired"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Model 'openai/gpt-5.2' is not allowed for this API key"
  }
}

429 Too Many Requests

string

Always "usage_limit_exceeded".

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "Usage limit exceeded: 1000.00 / 1000 tokens used"
  }
}

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "Organization has no credits remaining"
  }
}

500 Internal Server Error

When a server error occurs, the API may return a generic error response. These errors are rare and typically indicate an issue on Edgee’s side.

{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred. Please try again later."
  }
}

Handling Errors

When you receive an error response:

Check the HTTP status code to understand the general category of the error
Read the error code (error.code) to understand the specific issue
Review the error message (error.message) for additional context
Take appropriate action:
- 400 errors: Fix the request parameters and retry
- 401 errors: Check your API key and authentication headers
- 403 errors: Verify your API key permissions and status
- 429 errors: Read the error message. For a spend limit, wait for its reset or ask an administrator to change the limit; retrying does not restore the budget. For a provider rate limit, reduce traffic and retry with backoff.
- 5xx errors: Retry after a delay, or contact support if the issue persists

Budget exhaustion versus rate limiting

A key, member, squad, or routing budget can stop requests with a 429. Check usage limits and the active routing strategy. Repeated retries cannot replenish a budget. An all-time limit does not reset automatically.

Rate Limiting

If you exceed the rate limits, you will receive a 429 Too Many Requests response. We recommend implementing exponential backoff when you encounter rate limit errors:

Wait for the time specified in the Retry-After header (if present)
Retry the request with exponential backoff
Reduce the rate of requests to stay within limits

Get started

Integrations

Edgee SDKs

Application configuration

Gateway API

Error Response Format

HTTP Status Code Summary

Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Handling Errors

Budget exhaustion versus rate limiting

Rate Limiting

​Error Response Format

​HTTP Status Code Summary

​Error Codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

​Handling Errors

​Budget exhaustion versus rate limiting

​Rate Limiting

Error Response Format

HTTP Status Code Summary

Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Handling Errors

Budget exhaustion versus rate limiting

Rate Limiting