Skip to main content
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.
{
  "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 CodeStatusDescription
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required parameter, invalid model ID, model not found, or provider not supported.
401UnauthorizedNo valid API key provided, or the Authorization header is missing or malformed.
403ForbiddenThe 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.
404Not FoundThe requested resource doesn’t exist.
429Too Many RequestsToo many requests hit the API too quickly, or usage limit exceeded. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething 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
{
  "error": {
    "code": "bad_model_id",
    "message": "Invalid model ID: 'invalid-model'"
  }
}

​
401 Unauthorized

​
code
string
Always "unauthorized".
{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header"
  }
}

​
403 Forbidden

​
code
string
Always "forbidden".
{
  "error": {
    "code": "forbidden",
    "message": "API key is inactive"
  }
}

​
429 Too Many Requests

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

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