Core conceptsErrors and retries

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

FieldDescription
error.typeThe error category, set by the HTTP status. See Error types.
error.codeA stable code for the cause. Branch on the code, not on the message.
error.messageOne English sentence that explains the error.
error.fixWhat to change. Present when there is a known fix.
error.paramThe request field that caused the error. Present for field errors.
error.chargedWhether 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.retryabletrue when the same request can succeed if you send it again later.
request_idThe same value as the Request-Id response header.

Error types

StatusType
400invalid_request
401authentication
402billing
403permission
404not_found
409conflict
422invalid_request
500server
503unavailable

Error codes

StatusCodeWhen it happensRetry
400invalid_jsonThe body is not a JSON object.No
400invalid_idempotency_keyThe Idempotency-Key header is empty, longer than 255 characters or not printable ASCII.No
401api_key_missingNo Bearer key was sent in the Authorization header.No
401api_key_invalidThe key is malformed or unknown.No
401api_key_revokedThe key was deleted in the console.No
401api_key_disabledThe key is disabled in the console.No
401api_key_expiredThe key is past its expiration date.No
403insufficient_scopeThe key lacks the create permission. Keys created in the console have it.No
403workspace_forbiddenThe account that owns the workspace is suspended or scheduled for deletion.No
402insufficient_balanceThe hold for this request is larger than the workspace balance. Nothing was created.No
404not_foundAn upload id does not exist in this workspace, or no file was put to its upload address.No
422file_too_largeAn uploaded file is larger than max_bytes (50 MB). error.param names it.No
422invalid_parametersource is missing. The same code and status cover every field error; error.param names the field.No
422invalid_parameterimages is missing or empty, or has more photos than this mode accepts.No
422source_too_shortsource_duration_s is under 1 second.No
422source_too_longsource_duration_s, or the finished generation used as a source, is over 15 seconds.No
422idempotency_key_mismatchThe same Idempotency-Key was already used with a different body.No
503temporarily_unavailableThe request could not be completed just now.Yes
500internal_errorSomething failed on our side. The request_id identifies the request.Yes
503api_unavailableThe API is turned off.No
404not_foundNo generation with that id exists in this workspace.No
409not_cancelableThe generation already started or finished; only queued generations can be canceled.No
409not_deletableThe generation is still queued or in progress.No
422invalid_parameterThe upload content_type is not one the API accepts.No

When to retry

  • Retry only when error.retryable is true (temporarily_unavailable and internal_error). Wait a few seconds and send the same request again with the same Idempotency-Key, so a request that was in fact accepted is not created twice.
  • Do not resend a request that failed with 4xx until 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 Allowed for a method the endpoint does not accept, such as GET on an estimate endpoint.
  • 404 Not Found with an HTML page for a path that does not exist.

When you contact support, include the error's request_id if it has one.