Skip to main content

​
Error shape

Every error response uses the same shape: 
{
  "error": {
    "code": "string",
    "message": "human-readable explanation",
    "request_id": "req_01hq..."
  }
}
Include the request_id when reporting an issue — it lets us find the exact failing request in our logs.

​
HTTP status codes

StatusMeaning
200Success
202Accepted — generation in progress
400Invalid request body or parameters
401Missing or invalid API key
402Out of minutes for the month
404Story or endpoint not found
429Rate limit exceeded
500Internal server error
503Service temporarily unavailable

​
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.