Errors

Errors use a consistent envelope with a machine-readable code and a non-2xx HTTP status:

{
  "error": {
    "code": "not_found",
    "message": "video not found",
    "request_id": "req_01JZX4M8Q2TE9W"
  }
}

Some errors also carry a hint field with a suggested fix. Always log error.request_id — quote it in support requests and we can trace the exact call.

Error codes

Status	Code	When
400	invalid_url, invalid_handle, invalid_query	Missing or malformed url, handle, or query
400	unsupported_platform_url	The URL belongs to a different platform than the endpoint
400	invalid_limit	limit is not an integer in the allowed range
400	upstream_spend_ceiling	The request would exceed the per-request cost ceiling — lower limit
401	missing_api_key / invalid_api_key	No Authorization: Bearer header, or the key is wrong or revoked
402	out_of_credits	Credit balance too low for the call
404	not_found	Content is private, deleted, has no transcript, or the URL resolves to nothing
409	job_not_ready	Async job results requested before the job finished
429	rate_limited	Plan requests-per-minute exceeded — back off and retry
500	internal_error	Unexpected error on our side — safe to retry
502	upstream_failure	Transient fetch failure — safe to retry
504	upstream_timeout	The source took too long to respond — safe to retry

Retry guidance

import httpx, time

for attempt in range(5):
    r = httpx.get(url, headers=headers, timeout=120)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(2 ** attempt * 2)  # 2, 4, 8, 16, 32 seconds
        continue
    break

Retry 429 and 5xx with exponential backoff. Don’t retry 400, 401, 402 or 404 — the request itself needs to change.

Failed calls that return an error are not charged, and empty results are free up to 25 a day per account (after that, an empty result costs 1 credit).

A failed call from a valid key still appears in your usage log with its status code, its error code and credits_charged: 0 — on the dashboard’s Logs page or from GET /v1/usage — so a request that keeps failing is visible there even when nothing was billed.

Next: Rate limits · Output formats