Error Reference
Complete reference for all error codes, HTTP status codes, and troubleshooting steps for Cencori API errors.
Error Response Format
All errors follow a consistent JSON format:
error-response.json
HTTP Status Codes
| Status | Meaning | Typical Cause |
|---|---|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid parameters or malformed request |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Security violation or tier restriction |
404 | Not Found | Resource doesn't exist |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Server-side error |
503 | Service Unavailable | Provider is down or overloaded |
Common Error Codes
INVALID_API_KEY
401The provided API key is invalid, expired, or revoked.
Solutions:
- Verify the key is correct
- Check if the key has been revoked
- Generate a new key from the dashboard
- Ensure no whitespace in the key
SECURITY_VIOLATION
403Request blocked due to security filters (PII detection, prompt injection, harmful content).
Solutions:
- Review incident in dashboard for details
- Remove sensitive data from request
- Sanitize user input before sending
- Check for prompt injection patterns
RATE_LIMIT_EXCEEDED
429Too many requests in a short time period.
Solutions:
- Implement exponential backoff
- Check rate limit headers
- Upgrade your tier for higher limits
- Batch requests where possible
INSUFFICIENT_CREDITS
403Your organization has run out of credits.
Solutions:
- Top up credits in dashboard
- Enable auto-recharge
- Monitor credit balance
TIER_RESTRICTED
403The requested feature or provider requires a paid subscription.
Solutions:
- Upgrade to a paid tier
- Use Gemini models (free tier)
- Contact sales for enterprise access
INVALID_MODEL
400The specified model is not supported or doesn't exist.
Solutions:
- Check model name spelling
- See supported models
- Verify provider is configured
PROVIDER_ERROR
503The AI provider (OpenAI, Anthropic, etc.) returned an error or is unavailable.
Solutions:
- Retry after a short delay
- Try a different provider/model
- Check provider status pages
- Report persistent issues to support
Error Handling Best Practices
error-handling.ts
Rate Limit Headers
When rate limited, check these response headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per time window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when limit resets |
Retry-After | Seconds to wait before retrying |