Docs › Errors

Errors

Every error has the same JSON body:

{
  "message": "Daily limit reached (50 videos per 24 hours); try again later",
  "error": "DAILY_LIMIT",
  "requestId": "c0a8f1e2-5b7d-4c2a-8e6f-1b0d9c7a5e3f"
}

error: a stable code. Write your code against this. New codes may be added; handle unknown ones by HTTP status.
message: human-readable and safe to show to users. Its wording may change.
requestId: include it when you report a problem.
details (validation errors only): every problem found, as {field, message}. See Validation.

HTTP	error	Meaning	What to do
400	`INVALID_REQUEST`	Invalid body or parameter; the message names the field.	Fix the request.
401	`UNAUTHORIZED`	Missing, unknown or revoked API key.	Check the `Authorization` header.
403	`MISSING_AUTHENTICATION`	The request didn't reach the API with a key, usually because the base URL is missing its `/v1` path.	Check the base URL.
403	`FORBIDDEN`	Credentials not allowed.	Check your key.
403	`REQUEST_REJECTED`	Rejected before reaching the API, almost always a base URL missing `/v1`.	Check the base URL.
404	`NOT_FOUND`	No such video for you.	Check the ID.
404	`ROUTE_NOT_FOUND`	No such path.	Check the URL.
405	`METHOD_NOT_ALLOWED`	Wrong HTTP method; the message lists the right one.	Use the listed method.
403	`UPLOAD_TOKEN_SCOPE`	An upload token was used for something other than its one upload.	Use your API key on your server for everything else.
409	`UPLOAD_TOKEN_USED`	The upload token already made a video.	Make a new token.
403	`EDIT_TOKEN_SCOPE`	An edit token was used for something other than its one edit, or a clip uses a video the token wasn't made for.	Use your API key on your server for everything else.
409	`EDIT_TOKEN_USED`	The edit token already made its edit.	Make a new token.
400	`EDIT_TOO_LONG`	The edit is longer than its edit token's `maxSeconds`.	Shorten the edit.
409	`UPLOAD_INCOMPLETE`	Parts missing or the wrong size.	Upload the missing parts, then complete again.
409	`ALREADY_COMPLETED`	The upload already completed.	Use cancel to stop processing.
409	`ORIGINAL_UNAVAILABLE`	Reprocess: the original is missing or was deleted.	Upload again.
409	`EDIT_SOURCE_NOT_READY`	An edit clip's video hasn't finished.	Wait for `SUCCEEDED`.
409	`NOT_AN_UPLOAD`	An upload action on an edit.	Use cancel or reprocess.
409	`NOT_READY`	Thumbnails: the video hasn't finished processing.	Wait for `SUCCEEDED`.
409	`NO_CANDIDATES`	Thumbnails: the video was made before thumbnail choices existed.	Upload your own image, or reprocess.
400	`BILLING_ERROR`	Checkout or a plan change couldn't be completed; nothing was charged. Details are in our logs under the `requestId`.	Retry in a minute; if it persists, contact us with the `requestId`.
409	`ALREADY_SUBSCRIBED`	Checkout: this account already has a subscription.	Change plans with POST /billing/plan.
409	`NO_SUBSCRIPTION`	Plan change: there is no subscription yet.	Subscribe with POST /billing/checkout.
409	`NO_BILLING_ACCOUNT`	Portal: the account has never subscribed.	Subscribe first.
503	`BILLING_NOT_CONFIGURED`	Paid plans aren't set up on this service yet.	Try again later.
503	`BILLING_UNAVAILABLE`	The payment service is busy.	Retry shortly.
403	`OVERAGE_CAP_REACHED`	This month's overage reached your monthly overage cap; new processing is paused until the 1st (UTC).	Raise or remove the cap in your account, or wait for the new month.
409	`IDEMPOTENCY_KEY_REUSED`	Same Idempotency-Key, different request.	Use a new key.
409	`IDEMPOTENCY_IN_PROGRESS`	A request with this Idempotency-Key is still processing.	Retry in a moment.
409	`INVALID_STATE`	Not possible in the video's current state.	Read the message.
413	`TOO_LARGE`	The JSON body is too large (or a thumbnail image is over 2 MB).	Send less.
429	`RATE_LIMITED`	More than 5 requests per second.	Retry with backoff.
429	`QUOTA_EXCEEDED`	Daily request quota used up.	Try again tomorrow.
429	`DAILY_LIMIT`	Daily new-video limit reached.	Wait; it's a rolling 24 hours.
403	`PLAN_UPGRADE_REQUIRED`	The request uses something your plan doesn't include: a higher quality than its maximum (Free 720p, Starter 1080p), redaction, captions, screen recording (`camera`, `streaming` uploads). `details` names the field.	Remove it, lower `maxHeight`, or upgrade.
403	`PLAN_LIMIT_REACHED`	Free plan only: this month's processing minutes or the storage allowance is used up. Nothing is deleted.	Delete videos you don't need, wait for the 1st (UTC), or upgrade.
429	`VIDEOS_PAUSED`	New videos are paused for your account.	Contact the service owner.
502	`UPSTREAM_ERROR`	An internal inconsistency.	Report it with the `requestId`.
503	`UNAVAILABLE`	A temporary failure.	Retry with backoff.

Retry RATE_LIMITED, UNAVAILABLE and network errors with exponential backoff (e.g. 1 s, 2 s, 4 s… with jitter). Don't retry other 4xx errors unchanged.