Error codes
The thousands digit is the family
Every failure carries error.code, a stable string, and error.number, a stable integer. Branch on either. Select a code for its response shape and what to do about it.
36 codes
1xxxRequestThe request itself: shape, auth, idempotency, addressing5 codes
invalid_requestThe body failed validation.1001400invalid_cursorThe pagination cursor is malformed or expired.1002400unauthorizedMissing or invalid API key.1101401idempotency_conflictIdempotency-Key reused with a different body, or a request with that key is still in flight.1201409not_foundNo such resource: an unknown job or monitor id (or one that belongs to someone else), or a channel or playlist that does not exist or is not public.13014042xxxAccountBilling, plan limits, our per-key rate limiter4 codes
insufficient_creditsNot enough credits for the request.2001402Retrybatch_too_largeThe batch exceeds your plan's per-request cap.2002400monitor_limit_reachedThe account already has as many monitors as its plan allows.2003400rate_limitedYour account or key has reached a request or work-capacity limit.2101429Retry3xxxInputWell-formed, but this input cannot be served (permanent)6 codes
unsupported_platformThe input is not on a platform we serve.3001422endpoint_platform_mismatchThe platform is supported, but not by this endpoint: playlist listing covers YouTube and TikTok only, so an Instagram profile URL sent to /transcripts/playlist lands here.3002422audio_ineligibleAudio transcription cannot run on this input, so mode: "audio" (or ai_fallback) has nothing to work on.3004422invalid_inputThe input is not something we can transcribe: it is not a YouTube, TikTok or Instagram video (a profile, playlist or LIVE room link, an unsupported site), nor a direct media file URL.3005422audio_too_longThe media is longer than the AI-transcription length limit, so no audio was downloaded and nothing was charged.3006422drm_protectedThe source is DRM-protected and cannot be downloaded.30074224xxxContentReached the media; it has no transcript to give (permanent)13 codes
privateThe video is private.4001422unavailableThe video is unavailable (deleted, removed, terminated, or region-blocked).4002422members_onlyThe video is members-only / requires a channel membership.4003422age_restrictedThe video is age-restricted and not accessible without sign-in.4004422region_blockedThe video is geo-restricted for the fetch region.4005422not_publicInstagram returned no media for this post to a logged-out viewer: it is private, removed, or restricted to logged-in users.4006422live_streamThe video is a live stream: broadcasting now, scheduled, or ended without a published recording.4101422was_liveThe video was a live broadcast and has no caption track.4102422no_captionsNo caption track (manual or auto-generated) is available.4103422captions_disabledCaptions are disabled by the uploader.4104422no_speechNo detectable speech (e.g. music/ambient); nothing to transcribe.4105422no_audio_streamThe downloaded media carried no audio stream, so it could not be transcribed.4106422no_videoThe post has no video to transcribe: an Instagram photo post or photo carousel, or a page with no playable media.41074225xxxTransientThe fetch failed for now; retry with backoff6 codes
upstream_errorThe upstream fetch failed with a server-side error.5001503RetrytimeoutUpstream fetch timed out.5002503RetryconnectionCould not connect to the upstream service.5003503Retryproxy_unavailableThe upstream egress proxy refused the tunnel (billing, credentials, or exhausted quota).5004503Waitparse_errorUpstream returned a response that couldn't be parsed.5005503Retryupstream_unavailableThe transcript service could not be reached.5101502Retry9xxxServerOur fault2 codes
internal_errorUnexpected server error.9001500RetryunknownThe fetch failed for an unspecified reason.9002503RetryPer-video outcomes
A 200 batch can still carry failures
Batch requests return one outcome per video. Only ok items are billed. Inspect every item instead of treating the batch status as the result.
ok1 creditprocessingFree on this callerrorFreeerror block as a request-level failure, so branch on error.code; a transient code is worth retrying with backoff.HTTP status guide
Status first, then the code
Use the status to choose the broad response, then error.code for the exact cause.
- 400Bad RequestInvalid body, bad value, limit out of range, stale cursor, or a batch or monitor count over your plan's cap. Read error.code and error.issues / error.details.Fix
- 401UnauthorizedMissing, malformed, revoked, or unknown API key.Fix
- 402Payment RequiredNot enough credits to complete the request. Top up or upgrade your plan.Fix
- 404Not FoundThe referenced thing does not exist: a transcription job or monitor (or one belonging to another account), or a channel or playlist that a listing endpoint or a new monitor could not find (error.code not_found).Fix
- 409ConflictIdempotency-Key reused with a different body, or a request with that key is still in flight.Fix
- 422Unprocessable EntityPermanent failure for this input (unsupported platform, no captions, private, live, DRM-protected). error.code says which. The same input will fail the same way, so do not retry unchanged.Permanent
- 429Too Many RequestsRate limited: always your own key's per-plan limit, or a check of the same monitor already running. Honor the Retry-After header. (An upstream platform failing or blocking a fetch answers 503, never 429.)Retry-After
- 500Internal Server ErrorUnexpected server error. Retry with backoff; if it persists, send support the request_id.Retry
- 502Bad GatewayThe transcript service was unreachable. Safe to retry with backoff.Retry
- 503Service UnavailableTransient failure. Safe to retry with backoff; error.code says what failed.Retry