HTTP status codes
| Status Code | Meaning | Description |
|---|---|---|
200 | Success | Request completed successfully |
400 | Bad Request | Request validation failed |
401 | Unauthorized | Authentication error (missing/invalid API key) |
403 | Forbidden | Insufficient permissions or credits |
404 | Not Found | Endpoint/route not found |
409 | Conflict | Resource conflict |
429 | Too Many Requests | Concurrent request limit exceeded |
499 | Client Closed Request | Request was canceled by client |
500 | Internal Server Error | Server-side error |
502 | Bad Gateway | External service error |
Error response formats
Standard error response
Most errors follow this structure:Validation error (400)
Canceled request (499)
Internal error (500)
May return either format:Common error types
Authentication errors (401)
| Error Code | Message | Cause |
|---|---|---|
MISSING_API_KEY | Missing or invalid API key | No API key provided in request |
INVALID_API_KEY_FORMAT | Invalid API key format | API key format is incorrect |
INVALID_OR_EXPIRED_API_KEY | Invalid or expired API key | API key is invalid or has expired |
Permission errors (403)
| Error Code | Message | Cause |
|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | API key lacks required scopes |
INSUFFICIENT_CREDITS | Insufficient credits | Account has insufficient credits |
Rate Limiting (429)
External service errors (502)
Validation rules
Prompt validation
| Rule | Error Message |
|---|---|
| Must be 1-10,000 characters | ”Prompt cannot be empty” or “Prompt is too long” |
Country code validation
| Rule | Error Message |
|---|---|
| Must be valid ISO 3166-1 alpha-2 code | ”Invalid country code” |
Include parameter validation
| Parameter | Valid Values | Error Message |
|---|---|---|
include.markdown | true or false | ”Expected boolean” |
include.rawResponse (ChatGPT) | true or false | ”Expected boolean” |
include.searchQueries (ChatGPT) | true or false | ”Expected boolean” |
Troubleshooting
Common issues and solutions
401 Unauthorized- Check that your API key is included in the Authorization header
- Verify the API key format is correct
- Ensure the API key hasn’t expired
- Check your credit balance via response headers
- Top up your account credits
- Implement proper retry logic with exponential backoff
- Monitor concurrency headers to stay within limits
- Consider queuing requests if you hit limits
- Ensure prompt text is between 1-10,000 characters
- Use valid ISO 3166-1 alpha-2 country codes
- Check that include parameters are boolean values
- Implement retry logic for transient failures
- Monitor status pages for service availability
- Contact support if errors persist