When an error occurs, the gateway returns a JSON response with error details:
{
"status": "failure",
"message": "Error description",
"error": {
"type": "invalid_request_error",
"code": "invalid_api_key",
"message": "Incorrect API key provided"
}
}
HTTP Status Codes
The gateway uses standard HTTP status codes:
2xx Success
Resource created successfully
4xx Client Errors
Invalid request format or parameters
Invalid or missing authentication credentials
Valid credentials but insufficient permissions
Requested resource does not exist
Request format is valid but contains semantic errors
5xx Server Errors
Error from upstream provider
Service temporarily unavailable
Request timeout from upstream provider
Error Types
Authentication Errors
{
"status": "failure",
"message": "Provider authentication failed",
"error": {
"type": "authentication_error",
"code": "invalid_api_key"
}
}
- Missing
x-portkey-api-key header
- Invalid API key for the provider
- Expired API key
Invalid Request Errors
{
"status": "failure",
"message": "Invalid request parameters",
"error": {
"type": "invalid_request_error",
"code": "missing_required_parameter",
"param": "model"
}
}
- Missing required parameters
- Invalid parameter values
- Malformed JSON
Provider Errors
{
"status": "failure",
"message": "Provider request failed",
"error": {
"type": "provider_error",
"code": "model_not_found",
"provider": "openai"
}
}
- Invalid model name
- Model not available for your account
- Provider API is down
Rate Limit Errors
{
"status": "failure",
"message": "Rate limit exceeded",
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1677652320
Timeout Errors
{
"status": "failure",
"message": "Request timeout",
"error": {
"type": "timeout_error",
"code": "request_timeout"
}
}
- Provider taking too long to respond
- Network issues
- Large request or response
Error Handling Best Practices
Retry Strategy
Implement exponential backoff for retries:
import time
from openai import OpenAI
def make_request_with_retry(client, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello!"}]
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
wait_time = 2 ** attempt
time.sleep(wait_time)
Fallback Configuration
Use the gateway’s built-in fallback support:
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-H 'x-portkey-config: {
"strategy": {"mode": "fallback"},
"targets": [
{"provider": "openai", "api_key": "sk-..."},
{"provider": "anthropic", "api_key": "sk-ant-..."}
]
}' \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
Check Provider Status
Before making requests, you can check provider availability:
curl http://localhost:8787/v1/models \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..."
Debug Mode
Enable debug mode for detailed error information:
Enable debug mode (returns additional error details)
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-H "x-portkey-debug: true" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'