> ## 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

**error** `object` *required*

The error object.

**error.code** `string` *required*

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

**error.message** `string` *required*

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 | 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

**code** `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

```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

**code** `string`

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: <error details>"
  }
}
```

### 403 Forbidden

**code** `string`

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

**code** `string`

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**: 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](https://www.edgee.ai/docs/features/usage-limits.md) and the active [routing strategy](https://www.edgee.ai/docs/features/routing-strategies.md). 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:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.