Skip to main content

​
Error shape

Every error response uses the same shape:
Include the request_id when reporting an issue — it lets us find the exact failing request in our logs.

​
HTTP status codes

​
Error codes

​
Authentication

​
invalid_api_key
401
The API key is malformed, expired, or has been revoked.
​
missing_api_key
401
No Authorization header was sent, or the Bearer prefix is missing.

​
Validation

​
invalid_request
400
The request body failed schema validation. Check the details array in the response for the specific field.
​
invalid_id
400
The story ID does not match brief_<16-hex>.
​
not_found
404
No story exists for the requested ID.
​
failed
story status
Generation reached a terminal failure. Polling returns status: "failed" with an error message; no minutes are charged.
​
corrupt_cache_entry
500
A cached story exists but could not be parsed. Retry later or report the request_id.

​
Billing

​
insufficient_minutes
402
You’ve used your full monthly video allowance. Wait until your next billing cycle or upgrade your plan.

​
Rate limiting

​
rate_limit_exceeded
429
Too many requests. Back off for the number of seconds in the Retry-After header.

​
Service failures

​
server_misconfigured
503
Redis or billing configuration is unavailable, so generation cannot safely proceed.

​
Retry strategy

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.
Sleep for the exact number of seconds in the Retry-After header, then retry once.
Client errors won’t fix themselves. Log the request_id, fix the request, and try again.

​
Reporting bugs

Email the request_id from the error response to moshikarim@proton.me or open an issue on GitHub.