Ref: Error Codes

The API uses standard HTTP status codes and returns a JSON body with a message describing the error.

Additional Error Codes by Endpoint

Some endpoints return specific error codes:

Summary, Transcripts and Exports

Fetching summaries and transcripts is also limited per user, on top of the hourly request limit. These limits exist to prevent abuse and are set well above normal usage, so most integrations never reach them. Each plan has a short-term and a longer-term allowance, and there are two separate quotas:

• Summary: Get Episode Summary.
• Transcripts: Get Episode Transcripts, Export Episode as Markdown and Export Episode as SRT share one quota.

Only successful responses count. A request uses the quota only when it returns the summary, transcript or export; requests that fail with an invalid seq, not_found, copyright_denied, not_transcribed or not_translated do not use it.

When a quota is used up, the API returns HTTP 429 and tells you when it resets:

{
  "success": false,
  "error": "rate_limited",
  "message": "Weekly rate limit exceeded",
  "scope": "week",
  "retryAt": 1791849600000
}

scope names the allowance that was exceeded. Wait until retryAt (Unix timestamp in milliseconds) or for the number of seconds in the Retry-After header before retrying; earlier retries keep returning 429.

not_transcribed and not_translated responses carry a Retry-After header with the minimum number of seconds to wait. To wait for an episode to finish processing, poll Get Episode Status and fetch the content once its status is done.

Import Episode

Upload Audio

Process Episode

Ask a Question

Clips

Send to Notion

Send to Readwise Reader