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
201Resource created
202Accepted — generation in progress
400Invalid request body or parameters
401Missing or invalid API key
402Out of minutes for the month
403You don’t have access to the requested PR or resource
404PR, story, or endpoint not found
409Conflict (e.g. key name already used)
422Valid request shape but unprocessable (e.g. draft PR with no commits)
429Rate limit exceeded
500Internal server error
502Upstream GitHub or LLM provider failed
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.

​
Permissions

​
repo_access_denied
403
The GitHub account linked to your API key doesn’t have read access to this repo. For private repos, install the pull/story GitHub App or connect a GitHub identity with access.
​
pr_not_accessible
403
The PR is from a private repo the API key can’t see, or the repo owner has restricted automated access.

​
Validation

​
invalid_request
400
The request body failed schema validation. Check the details array in the response for the specific field.
​
pr_not_found
404
No PR exists at the given owner/repo/number.
​
draft_pr_skipped
422
The PR is in draft state and has no commits to narrate. Mark it ready for review to generate a pull story.

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

​
Upstream failures

​
github_upstream_error
502
GitHub returned an error while fetching the PR diff. Usually transient — retry after 30 seconds.
​
generation_failed
500
The pull story couldn’t be generated. The story’s status is set to failed and no minutes are charged. Call POST /v1/stories again to retry.

​
Retry strategy

Retry with 1s, 2s, 4s, 8s delays. Give up after 4 attempts. Include a unique Idempotency-Key header (any UUID) to avoid accidental duplicate stories.
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.