Troubleshooting

Reading an error response

Every failure carries a code, a number and a docs link. Which ones a retry can fix, and which never will.

Every error response has the same block:

json

{
  "ok": false,
  "request_id": "req_…",
  "error": {
    "code": "no_captions",
    "number": 4103,
    "message": "No caption track is available for this video.",
    "docs": "https://transcriptfetch.com/docs/errors/no_captions",
    "retry_with": { "mode": "audio" }
  }
}

Branch on code (a stable string) or number (a stable integer), never on the message text. The number's first digit is the family, which tells you what to do even for a code you have not seen:

Family	Meaning	What to do
1xxx	The request itself: body, key, idempotency, an unknown job id	Fix the request
2xxx	Your account: credits, plan caps, request and work-capacity limits	Top up, split the batch, or wait for `Retry-After`
3xxx	This input cannot be served: wrong platform, wrong endpoint	Change the input
4xxx	The media has no transcript to give: private, live, no captions, no speech	Nothing, unless `retry_with` is present
5xxx	Transient: the fetch failed for now	Retry with backoff
9xxx	Our fault	Retry once; send us the `request_id` if it persists

Three optional fields appear at most one at a time. retry_with is the request change that would succeed (merge it into your body and send again). details is structured specifics for the few codes that have them, such as { "max": 50, "sent": 120 } on batch_too_large. issues lists field-level validation problems on invalid_request.

The four worth handling explicitly

401 unauthorized (1101). Missing, malformed, revoked or unknown key. The usual cause is a bare key with no Bearer prefix. Retrying will not help until the header is fixed.

402 insufficient_credits (2001). The key is valid but the balance cannot cover the request. Retry once credits are available; nothing was charged.

422, any 3xxx or 4xxx code. The input cannot work as sent. This is the family that never succeeds on retry. A retry loop here burns requests for nothing. The one exception is spelled out for you: when the error carries retry_with, that changed request will work.

429 rate_limited (2101). Your account or key has reached a request or work-capacity limit. Wait the number of seconds in Retry-After, then continue. A platform blocking a fetch answers 503, never 429.

Failed requests are never charged, so no failure carries a usage block. Every code has its own page with causes and fixes at /docs/errors/<code>, and /docs/errors/<number> works too. If you are still stuck, the support chat reaches a person.

Still stuck?

Open the chat launcher, bottom right, and include your request_id if you have one. Or email [email protected].