Errors
Common Open API error shape and status codes.
Errors
Open API errors use JSON response bodies when the request reaches the API layer. Network failures, CDN failures, and binary response interruptions may not have this exact shape, so your client should handle both structured API errors and transport errors.
Every endpoint uses the same bearer authentication context:
Authorization: Bearer YOUR_API_TOKEN{
"code": "invalid_request",
"message": "The request payload is invalid.",
"requestId": "req_xxx"
}Status Codes
| Status | Meaning | Typical action |
|---|---|---|
400 | Invalid request body, path parameter, query parameter, or media URL | Fix the request before retrying |
401 | Missing, malformed, revoked, or disabled API token | Stop retries and refresh credentials |
402 | Insufficient credits, API quota, or provider allocation | Stop the batch and show billing state |
404 | Resource id is unknown for the authenticated account | Refresh local records |
409 | Resource is in a state that conflicts with the operation | Wait or remove dependencies |
422 | Media was accepted but cannot be processed | Ask for different input media |
429 | Rate limit exceeded | Retry with exponential backoff |
500 | Server error | Retry a small number of times and log requestId |
Request Logging
Log the endpoint, HTTP method, status, code, requestId, and your own internal job id. Do not log bearer tokens, full user text, or private media URLs unless your privacy policy and support workflow explicitly allow it.
For async endpoints, include both the API task id and your internal database id in logs. That makes it possible to reconcile retries without creating duplicate work.
Billing And Credits
Not every error has the same billing meaning. Validation failures normally happen before media work starts. Processing failures may happen after a task was accepted. For user-facing billing questions, compare the task status with a fresh Profile read instead of inferring cost from HTTP status alone.
Retry Policy
Retry 429 and some 500 responses with backoff. Do not blindly retry 400, 401, or 402; those require request, credential, or billing changes. For create endpoints, persist the returned id before retrying any follow-up operation.