Core concepts
Errors and retries
Read the error body, find the cause and decide when to retry.
Every error from an endpoint has the same JSON body. A request without a key, for example, returns 401:
{
"error": {
"type": "authentication",
"code": "api_key_missing",
"message": "No API key was sent.",
"fix": "Send the key as Authorization: Bearer sera_sk_...",
"charged": false,
"retryable": false
},
"request_id": "req_k38ss8hmb36g9308sy351ot3yi"
}Error fields
| Field | Description |
|---|---|
error.type | The error category, set by the HTTP status. See Error types. |
error.code | A stable code for the cause. Branch on the code, not on the message. |
error.message | One English sentence that explains the error. |
error.fix | What to change. Present when there is a known fix. |
error.param | The request field that caused the error. Present for field errors. |
error.charged | Whether the failed request cost anything. It is false on every error the API returns: a generation holds money only after it was accepted with 202, and a failed generation restores its hold. |
error.retryable | true when the same request can succeed if you send it again later. |
request_id | The same value as the Request-Id response header. |
Error types
| Status | Type |
|---|---|
400 | invalid_request |
401 | authentication |
402 | billing |
403 | permission |
404 | not_found |
409 | conflict |
422 | invalid_request |
500 | server |
503 | unavailable |
Error codes
| Status | Code | When it happens | Retry |
|---|---|---|---|
400 | invalid_json | The body is not a JSON object. | No |
400 | invalid_idempotency_key | The Idempotency-Key header is empty, longer than 255 characters or not printable ASCII. | No |
401 | api_key_missing | No Bearer key was sent in the Authorization header. | No |
401 | api_key_invalid | The key is malformed or unknown. | No |
401 | api_key_revoked | The key was deleted in the console. | No |
401 | api_key_disabled | The key is disabled in the console. | No |
401 | api_key_expired | The key is past its expiration date. | No |
403 | insufficient_scope | The key lacks the create permission. Keys created in the console have it. | No |
403 | workspace_forbidden | The account that owns the workspace is suspended or scheduled for deletion. | No |
402 | insufficient_balance | The hold for this request is larger than the workspace balance. Nothing was created. | No |
404 | not_found | An upload id does not exist in this workspace, or no file was put to its upload address. | No |
422 | file_too_large | An uploaded file is larger than max_bytes (50 MB). error.param names it. | No |
422 | invalid_parameter | source is missing. The same code and status cover every field error; error.param names the field. | No |
422 | invalid_parameter | images is missing or empty, or has more photos than this mode accepts. | No |
422 | source_too_short | source_duration_s is under 1 second. | No |
422 | source_too_long | source_duration_s, or the finished generation used as a source, is over 15 seconds. | No |
422 | idempotency_key_mismatch | The same Idempotency-Key was already used with a different body. | No |
503 | temporarily_unavailable | The request could not be completed just now. | Yes |
500 | internal_error | Something failed on our side. The request_id identifies the request. | Yes |
503 | api_unavailable | The API is turned off. | No |
404 | not_found | No generation with that id exists in this workspace. | No |
409 | not_cancelable | The generation already started or finished; only queued generations can be canceled. | No |
409 | not_deletable | The generation is still queued or in progress. | No |
422 | invalid_parameter | The upload content_type is not one the API accepts. | No |
When to retry
- Retry only when
error.retryableistrue(temporarily_unavailableandinternal_error). Wait a few seconds and send the same request again with the sameIdempotency-Key, so a request that was in fact accepted is not created twice. - Do not resend a request that failed with
4xxuntil you change what the error points to. - Use increasing waits with random jitter between attempts, and stop after a few tries.
Failed generations
A generation that was accepted and later failed is not an error response. Its status is failed, error.code and error.message say why, and its hold is restored. Create a new generation to try again.
Responses outside the error format
Some responses come from the web server before an endpoint runs. They have no JSON error body and no Request-Id header:
405 Method Not Allowedfor a method the endpoint does not accept, such asGETon an estimate endpoint.404 Not Foundwith an HTML page for a path that does not exist.
When you contact support, include the error's request_id if it has one.