Error shape
Every error response uses the same shape:request_id when reporting an issue — it lets us find the exact failing request in our logs.
HTTP status codes
Error codes
Authentication
401
The API key is malformed, expired, or has been revoked.
401
No
Authorization header was sent, or the Bearer prefix is missing.Validation
400
The request body failed schema validation. Check the
details array in the response for the specific field.400
The story ID does not match
brief_<16-hex>.404
No story exists for the requested ID.
story status
Generation reached a terminal failure. Polling returns
status: "failed" with an error message; no minutes are charged.500
A cached story exists but could not be parsed. Retry later or report the
request_id.Billing
402
You’ve used your full monthly video allowance. Wait until your next billing cycle or upgrade your plan.
Rate limiting
429
Too many requests. Back off for the number of seconds in the
Retry-After header.Service failures
503
Redis or billing configuration is unavailable, so generation cannot safely proceed.
Retry strategy
5xx errors: exponential backoff
5xx errors: exponential backoff
Retry with
1s, 2s, 4s, 8s delays. Give up after 4 attempts. Story creation is idempotent by brief content, so an identical JSON brief returns the same story ID.429: respect Retry-After
429: respect Retry-After
Sleep for the exact number of seconds in the
Retry-After header, then retry once.4xx except 429: don't retry
4xx except 429: don't retry
Client errors won’t fix themselves. Log the
request_id, fix the request, and try again.Reporting bugs
Email therequest_id from the error response to moshikarim@proton.me or open an issue on GitHub.