Complete reference for all API error codes, their causes, and solutions. Learn how to handle errors gracefully in your applications.
All API errors follow a consistent JSON structure for easy parsing and handling:
{
"error": "Error Title",
"message": "Detailed error description",
"code": "ERROR_CODE",
"requestId": "req_abc123xyz",
"timestamp": "2025-01-18T14:30:00Z",
"details": {
// Additional context-specific information
}
}Errors caused by invalid requests from the client
Invalid request body, parameters, or formatting
Common Causes:
Solution:
Verify request body matches API specification. Check prompt is a string and within size limits.
Example Response:
{
"error": "Bad Request",
"message": "prompt is required and must be a string",
"code": "VALIDATION_ERROR",
"field": "prompt",
"requestId": "req_abc123"
}Missing or invalid API key
Common Causes:
Solution:
Verify API key in dashboard and ensure X-API-Key header is included with valid key.
Example Response:
{
"error": "Unauthorized",
"message": "Invalid or missing API key",
"code": "AUTHENTICATION_REQUIRED",
"requestId": "req_abc123"
}Valid key but insufficient permissions or quota
Common Causes:
Solution:
Check rate limits and account status in dashboard. Wait before retrying or upgrade plan.
Example Response:
{
"error": "Forbidden",
"message": "Rate limit exceeded. Retry after 3600 seconds",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 3600,
"requestId": "req_abc123"
}Request body exceeds maximum size
Common Causes:
Solution:
Reduce prompt size or split into multiple requests. Maximum prompt size is 100,000 characters.
Example Response:
{
"error": "Payload Too Large",
"message": "Prompt exceeds maximum size of 100KB",
"code": "PAYLOAD_TOO_LARGE",
"maxSize": 100000,
"actualSize": 150000,
"requestId": "req_abc123"
}Rate limit exceeded for your tier
Common Causes:
Solution:
Implement exponential backoff and retry logic. Check X-RateLimit-* headers for limits.
Example Response:
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Try again in 3600 seconds",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 3600,
"limit": 100,
"remaining": 0,
"reset": 1705590000,
"requestId": "req_abc123"
}Errors caused by server-side issues
Unexpected server-side error during processing
Common Causes:
Solution:
Retry request with exponential backoff. If persists, contact support with requestId.
Example Response:
{
"error": "Internal Server Error",
"message": "An error occurred during compression",
"code": "INTERNAL_ERROR",
"requestId": "req_abc123"
}Service temporarily unavailable
Common Causes:
Solution:
Wait and retry. Check status page for maintenance schedules.
Example Response:
{
"error": "Service Unavailable",
"message": "Service temporarily unavailable. Try again later",
"code": "SERVICE_UNAVAILABLE",
"retryAfter": 60,
"requestId": "req_abc123"
}Request timeout during processing
Common Causes:
Solution:
Increase maxTimeMs option or reduce prompt size. Retry with smaller payload.
Example Response:
{
"error": "Gateway Timeout",
"message": "Request timeout after 30000ms",
"code": "GATEWAY_TIMEOUT",
"timeout": 30000,
"requestId": "req_abc123"
}Application-specific error codes returned in the code field:
AUTHENTICATION_REQUIREDAPI key missing or invalid
VALIDATION_ERRORRequest validation failed
RATE_LIMIT_EXCEEDEDToo many requests
PAYLOAD_TOO_LARGERequest exceeds size limit
INTERNAL_ERRORServer-side error
SERVICE_UNAVAILABLEService temporarily down
GATEWAY_TIMEOUTRequest processing timeout
COMPRESSION_FAILEDCompression algorithm failed
async function compressWithRetry(
prompt: string,
maxRetries = 3
): Promise<CompressResponse> {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await compress(prompt);
} catch (error: any) {
const isRetryable = [429, 500, 503, 504].includes(error.status);
const isLastAttempt = attempt === maxRetries - 1;
if (!isRetryable || isLastAttempt) {
throw error;
}
// Exponential backoff: 1s, 2s, 4s, 8s...
const delay = Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}async function handleRateLimit(error: any): Promise<void> {
if (error.code === 'RATE_LIMIT_EXCEEDED') {
const retryAfter = error.retryAfter || 60;
console.log(`Rate limit hit. Retrying in ${retryAfter} seconds`);
// Wait for retry period
await new Promise(resolve =>
setTimeout(resolve, retryAfter * 1000)
);
// Check rate limit headers
const remaining = error.remaining || 0;
const reset = error.reset || Date.now() + retryAfter * 1000;
console.log(`Rate limit resets at: ${new Date(reset * 1000)}`);
}
}function classifyError(error: any): 'client' | 'server' | 'network' {
const status = error.status;
if (status >= 400 && status < 500) {
return 'client'; // Fix in your code
}
if (status >= 500) {
return 'server'; // Retry or contact support
}
return 'network'; // Network/connection issue
}
function shouldRetry(error: any): boolean {
const retryableStatuses = [429, 500, 502, 503, 504];
const retryableCodes = [
'RATE_LIMIT_EXCEEDED',
'INTERNAL_ERROR',
'SERVICE_UNAVAILABLE',
'GATEWAY_TIMEOUT'
];
return retryableStatuses.includes(error.status) ||
retryableCodes.includes(error.code);
}Always log requestId from errors for debugging and support
Set request timeouts to prevent hanging connections
Implement exponential backoff for transient errors
Show user-friendly messages, log technical details
All responses include rate limit information in headers:
X-RateLimit-LimitMaximum requests allowed per hour
100X-RateLimit-RemainingRequests remaining in current window
75X-RateLimit-ResetUnix timestamp when limit resets
1705590000Retry-AfterSeconds to wait before retrying (only on 429/503)
3600