API reference/Error codes
API error codes
Every HTTP status and error code the TubeExtract API returns, plus the job failure codes, what they mean and whether to retry.
Two separate things fail: the HTTP call, and the job. They have different codes.
HTTP statuses
Status
Code
When
400invalid_requestMalformed body. The message names the field, and
details carries the full list.400schema_invalidA column type or name the API cannot use: an unknown type, an
enum without options, or a list on the first column. The message names the column.400batch_too_largeMore than 200 videos in one call. Nothing is queued.
401unauthorizedMissing or unknown API key.
402insufficient_creditsThe workspace has no credits to spend, or has reached its hard cap.
403plan_limitThe plan does not include it: webhooks on Free, or more API keys than the plan allows.
403forbiddenThe workspace has been closed.
403email_unverifiedThe account that created the key has not confirmed its email address. Confirm it from the link we sent, then retry.
404not_foundschema_not_foundNo such job, key, endpoint or schema — or it belongs to another workspace. The two are deliberately indistinguishable.
409idempotency_conflictAn
Idempotency-Key was reused with a different body.429rate_limitedOver the plan’s per-minute limit. Honour
Retry-After.5xxinternal_errorOurs. Retry with backoff; nothing was charged.
The body is always { "error": { "code", "message", "details"? } }. Branch on code, not on the message: codes are stable, messages are written for people and may change.
Job error codes
These arrive on a video that reached failed, in its error field, with retryable set as below. None of them are charged.
Code
Meaning
Retry
no_captionsNo caption track we can read. There is no fallback.No
video_unavailablePrivate, deleted or region-blocked.No
schema_invalidThe extraction engine rejected the schema before running. Rare, because a bad schema is already refused with 400 when submitted.No
captions_fetch_failedUpstream caption fetch failed or timed out.Yes
internal_errorOurs. Worth retrying once.Yes
insufficient_creditsThe workspace could not pay for this video once its length was known.No
Was this page useful?Tell us what was missing