Error Handling
All API errors follow a consistent format, making it easy to handle failures programmatically.Error Response Format
Every error response includes:| Field | Type | Description |
|---|---|---|
success | boolean | Always false for errors |
error.code | string | Machine-readable error code |
error.message | string | Human-readable description |
error.details | object | Additional context (optional) |
requestId | string | Unique request ID for debugging |
Job Error Codes
These errors occur when working with jobs, models, and user operations:| Code | HTTP Status | Description |
|---|---|---|
MODEL_NOT_FOUND | 404 | The specified model slug does not exist |
MODEL_VERSION_NOT_FOUND | 404 | The specified model version does not exist |
MODEL_VERSION_NOT_ACTIVE | 400 | The model version exists but is not currently active |
INVALID_MODEL_SLUG | 400 | The model slug format is invalid |
MODEL_ACCESS_DENIED | 403 | You do not have access to this model |
INSUFFICIENT_BALANCE | 402 | Your account balance is too low for this job |
INVALID_INPUT | 400 | The input parameters are invalid or missing |
JOB_NOT_FOUND | 404 | The specified job ID does not exist |
JOB_CANNOT_BE_CANCELLED | 400 | The job is in a state that cannot be cancelled |
CONCURRENT_JOBS_EXCEEDED | 429 | Too many jobs running simultaneously |
INVALID_WEBHOOK_URL | 400 | The provided webhook URL is not valid |
USER_NOT_FOUND | 404 | The user account was not found |
USER_BANNED | 403 | The user account has been banned |
USER_INACTIVE | 403 | The user account is inactive |
UNAUTHORIZED_ACCESS | 403 | You are not authorized to perform this action |
PUBSUB_PUBLISH_FAILED | 503 | Internal message queue failure |
INTERNAL_ERROR | 500 | An unexpected server error occurred |
Authentication Error Codes
These errors occur during authentication and authorization:| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | No authentication credentials provided |
INVALID_API_KEY | 401 | The API key is not valid |
API_KEY_INACTIVE | 401 | The API key has been deactivated |
API_KEY_EXPIRED | 401 | The API key has expired |
IP_NOT_WHITELISTED | 403 | Request IP is not in the allowed list |
OPERATION_NOT_ALLOWED | 403 | The API key does not have permission for this operation |
INVALID_WORKER_SECRET | 401 | Invalid worker authentication secret |
INVALID_SESSION | 401 | The session token is invalid or expired |
FORBIDDEN | 403 | Access denied |
CONFIG_ERROR | 500 | Server configuration error |
Retry Strategy
Not all errors should be retried. Use the HTTP status code to determine the right approach:Retryable Errors
503 Service Unavailable
Temporary server issue. Retry with exponential backoff:Start with 1 second, max 60 seconds, up to 5 attempts.
429 Too Many Requests
Rate limit hit. Check the
retryAfter field in the response and wait the specified duration before retrying.Non-Retryable Errors
| Status | Action |
|---|---|
| 400 Bad Request | Fix the request parameters and resubmit |
| 401 Unauthorized | Check your API key and authentication |
| 402 Payment Required | Add funds to your account |
| 403 Forbidden | Verify your permissions and access rights |
| 404 Not Found | Check the resource ID or model slug |
Implementation Examples
Best Practices
Log Request IDs
Store the
requestId from every response for debugging and support requests.Handle Gracefully
Always check
success field before accessing data. Never assume a request succeeded.Use Estimate First
Call the estimate endpoint before submitting to catch
INSUFFICIENT_BALANCE early.Monitor Error Rates
Track error codes in your application to identify patterns and potential issues.