Skip to main content

​
Error contract

Branch on error.reason and error.retryable. Do not match message text. Messages are short, sanitized explanations and may be clarified without changing the stable reason. HTTP errors use this additive envelope (the example illustrates the general credit error shape; /v1/execute reports credit admission failures later in execution state):
code and category remain for clients built against the earlier envelope. New integrations should use reason. The X-Request-ID response header matches error.request_id. Error responses send Cache-Control: no-store.

​
Details

A request that fails because one field is wrong also carries error.details, so you can correct the request without guessing:
A body that fails schema validation instead carries error.details.field_errors, one entry per field. details is sanitized and never echoes a submitted value, so read field and issue rather than matching on text. Not every error has details; treat it as optional.

​
Stable reasons

For the managed execution flow, distinguish HTTP rejection from asynchronous admission and job failures. A status read returning HTTP 200 can still contain a failed execution.

​
Execution admission

POST /v1/execute accepts durable work before checking credits, quota, and active-job admission. A non-retryable admission failure is a failed execution, returned by GET /v1/executions/{execution_id} and its done event:
There is no submit-time 402 for these execution admission failures. Retryable admission failures stay queued and are retried by the service; callers do not receive too_many_active_jobs for that stage. Synchronous request throttling can still return 429, conflicting request identity returns 409, and unavailable sprite access can return 403. Request validation and authentication happen before acceptance.

​
Accepted jobs

A job that fails after acceptance reports a sanitized failure on its canonical image_job:
The lowercase code: generation_failed is retained for older clients. New clients should use reason and retryable.

​
Billing and retries

Image operations reserve one credit. Sprite requests reserve their complete approved price. A successful delivery settles that reservation once. Failure or timeout before delivery restores it once. Sprite requests do not offer customer cancellation. Duplicate callbacks, worker redelivery, and a repeated cancel cannot add another charge or restoration. For retryable failures, first read the saved execution. If you still need to resend, use the original Idempotency-Key with the identical body. A new key can create new paid work. Public errors never include provider or model names, private responses, prompts, filenames, asset URLs, credentials, stack traces, routing details, or internal database state. insufficient_frames means the animation cannot supply enough distinct frames. The hold is restored; request fewer frames or use a different reference. No frames are silently duplicated or interpolated. prompt_policy_blocked and feature_unavailable are reserved for restricted product hosts that share this API. Requests to the primary DreamLayer host never return them. Both are refused before any credit is reserved, so nothing is charged and there is nothing to retry with the same key.