API reference
Error codes & outcomes
Request-level failures return a canonical error object with a machine-readable code. Per-video results inside a batch carry an outcome instead, and only successful ones are billed.
Canonical error codes
| code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid API key. |
invalid_request | 400 | Body failed validation - see error.issues. |
insufficient_credits | 402 | Not enough credits for the request. |
rate_limited | 429 | Per-key rate limit exceeded. Retry after backoff. |
idempotency_conflict | 409 | Idempotency-Key reused with a different body, or a request with that key is still in flight. |
unsupported_platform | 422 | The URL has no captions and is not on a platform AI transcription supports (YouTube, TikTok, Instagram, X, Facebook, or a direct media file). |
upstream_unavailable | 502 | The transcript service was unreachable. Safe to retry. |
internal_error | 500 | Unexpected server error. |
HTTP status codes
| Status | Name | Meaning |
|---|---|---|
| 400 | Bad Request | Invalid body, missing/unknown endpoint, bad value, or limit out of range. Check the issues array in the response. |
| 401 | Unauthorized | Missing, malformed, revoked, or unknown API key. |
| 402 | Payment Required | Not enough credits to complete the request. Top up or upgrade your plan. |
| 409 | Conflict | Idempotency-Key reused with a different body, or a request with that key is still in flight. |
| 429 | Too Many Requests | Per-key rate limit exceeded. Wait the number of seconds in Retry-After and retry. |
| 502 | Bad Gateway | The transcript service was unreachable. Safe to retry with backoff. |
Per-video outcomes
| outcome | Charged | Meaning |
|---|---|---|
ok | 1 credit | Transcript (or video list) returned successfully. |
no_transcript | Free | The video exists but has no available transcript/captions. |
blocked | Free | The upstream request was blocked. Retry later. |
error | Free | An unexpected error occurred fetching the source. |
A 200 can still carry a non-success outcome. Inside a batch, each video reports its own
outcome, only ok outcomes are billed, everything else is free.