> ## Documentation Index
> Fetch the complete documentation index at: https://www.edgee.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> How Edgee API responds when errors occur.
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
The error object.
A machine-readable error code that briefly explains the error reported.
A human-readable message providing more details about the error.
```json Error Response Example theme={"dark"}
{
"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 | Too many requests hit the API too quickly, or usage limit exceeded. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 | Server Errors | Something went wrong on Edgee's end. (These are rare.) |
## Error Codes
### 400 Bad Request
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
```json Bad Model ID theme={"dark"}
{
"error": {
"code": "bad_model_id",
"message": "Invalid model ID: 'invalid-model'"
}
}
```
```json Model Not Found theme={"dark"}
{
"error": {
"code": "model_not_found",
"message": "Model 'openai/gpt-1' not found"
}
}
```
```json Provider Not Supported theme={"dark"}
{
"error": {
"code": "provider_not_supported",
"message": "Provider 'anthropic' is not supported for model 'openai/gpt-5.2'"
}
}
```
```json Streaming Not Supported theme={"dark"}
{
"error": {
"code": "streaming_not_supported",
"message": "Streaming for Messages API is only supported when the model uses the Anthropic provider"
}
}
```
### 401 Unauthorized
Always `"unauthorized"`.
```json Missing Authorization Header theme={"dark"}
{
"error": {
"code": "unauthorized",
"message": "Missing Authorization header"
}
}
```
```json Invalid Authorization Format theme={"dark"}
{
"error": {
"code": "unauthorized",
"message": "Invalid Authorization header format"
}
}
```
```json Failed to Retrieve API Key theme={"dark"}
{
"error": {
"code": "unauthorized",
"message": "Failed to retrieve API key: "
}
}
```
### 403 Forbidden
Always `"forbidden"`.
```json Inactive Key theme={"dark"}
{
"error": {
"code": "forbidden",
"message": "API key is inactive"
}
}
```
```json Expired Key theme={"dark"}
{
"error": {
"code": "forbidden",
"message": "API key has expired"
}
}
```
```json Model Not Allowed theme={"dark"}
{
"error": {
"code": "forbidden",
"message": "Model 'openai/gpt-5.2' is not allowed for this API key"
}
}
```
### 429 Too Many Requests
Always `"usage_limit_exceeded"`.
```json Usage Limit Exceeded theme={"dark"}
{
"error": {
"code": "usage_limit_exceeded",
"message": "Usage limit exceeded: 1000.00 / 1000 tokens used"
}
}
```
```json No Credits Remaining theme={"dark"}
{
"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.
```json Server Error theme={"dark"}
{
"error": {
"code": "internal_error",
"message": "An internal error occurred. Please try again later."
}
}
```
## Handling Errors
When you receive an error response:
1. **Check the HTTP status code** to understand the general category of the error
2. **Read the error code** (`error.code`) to understand the specific issue
3. **Review the error message** (`error.message`) for additional context
4. **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**: Implement exponential backoff and retry logic
* **5xx errors**: Retry after a delay, or contact support if the issue persists
## 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:
1. Wait for the time specified in the `Retry-After` header (if present)
2. Retry the request with exponential backoff
3. Reduce the rate of requests to stay within limits