API errors and limits

Errors come in two shapes. A request that is refused gets an HTTP error with a snake_case code. A job that fails later carries the engine's error, with an upper-case code. The same upper-case codes are used by the CLI and the MCP server. A code that means "out of minutes" in one place means it everywhere.

The error object

A refused request

A request that cannot be accepted gets an HTTP status and this body:

{  "error": {    "code": "source_auth_required",    "message": "Instagram needs a login to read this video.",    "engineCode": "SOURCE_AUTH_REQUIRED",    "hint": "Download the video or its audio yourself and upload the file instead.",    "retryable": false,    "stage": "resolve"  }}

The hint in this example tells people to download the file and upload it.

Some errors carry more fields: minutesNeeded and minutesRemaining on quota_exceeded and anonymous_limit, and upload_id when a multipart request was refused after the file arrived. A Retry-After header says how many seconds to wait on a 429 or 503.

A failed job

A job that fails, and the error event that ends its stream, carry the engine's error:

{  "code": "SOURCE_BLOCKED",  "message": "YouTube refused the download (HTTP 403).",  "retryable": true,  "scope": "job",  "stage": "download",  "hint": "Update yt-dlp: brew upgrade yt-dlp"}

For a job, the error is in error on GET /v1/jobs/:id. A canceled job has the code CANCELLED. Error messages never contain keys or credentials. When Scribiz's own connection to the model service fails or runs out of quota, you see INTERNAL or RATE_LIMIT with a hint to try again, never an account problem of yours.

HTTP statuses

A source error from the engine becomes the lower-case form of its code with the engine code beside it: source_unavailable with engineCode: "SOURCE_UNAVAILABLE". Its status is 422 for a problem with the link, 413 for a video that is too long, and 502 to 504 for a problem upstream.

Error codes

These are the engine's codes. Jobs, the event stream, the CLI and MCP use them as written. The API's own refusals use the snake_case form with the engine code beside it. Every code, whether a retry can help, and the exit code the CLI uses. See Commands for the exit codes.

The input

The source

The service

The run

Retrying safely

• Retry 429, 5xx, timeouts and dropped connections. Do not retry other 4xx responses: the same request will fail the same way.
• Honor Retry-After on a 429 or 503. Without it, wait 1, 2, 4 and 8 seconds with a little random jitter, and stop after a few tries.
• Send an Idempotency-Key with POST /v1/context. Then a retry cannot create a second job or a second charge.
• A job that failed with retryable: true can be started again with a new request. A failed job keeps its audio for the retry, so work that already finished, such as audio pieces that were transcribed, is not paid for twice.
• Scribiz retries on its own, inside a job, for network errors, timeouts and rate limits. A job reports failed only after that.
• A job that is interrupted, for example by a restart of the service, is queued again on its own, up to three times. Its stream shows a requeued event.

Limits

Mac Lifetime accounts have the free plan's limits and a one-time 300 minutes.

Plan limits are the same ones shown on the pricing page and in Minutes and billing. For a larger input, cut the audio yourself and upload that, or use the CLI, which cuts the audio on your machine. With your own Gemini key it has no limit from Scribiz. Signed in to an account, it uses that account's minutes.

Usage and metering

Hosted jobs are charged in minutes of source video times the multiplier of what ran: captions 0.1 (and, without an account, 30 lookups a day), Listen 1, Watch 1, Both 2, a question 0.1, a stored result 0. The charge is made when the job ends, from what ran. A canceled or failed job is not charged. Two callers who share one run of the same video each pay the minutes, and the upstream cost is recorded once.

Scribiz measures usage from what the model service reports it processed, never from a number the client sends. So there is no header to set, and no way to under-report. See Minutes and billing.

When the hosted tool is busy

If anonymous use has spent the day's budget, Listen and Watch are switched off for anonymous callers for a while. A request that needs them answers 503 with busy, and Auto falls back to captions when captions exist: the 202 carries degraded. Captions keep working. Signed-in accounts are not affected. GET /v1/status shows the state under free_tier.listen_watch. The MCP server without a key has its own daily limit across all callers. It cannot use up the web tool's, and the web tool cannot use up its.

When the queue is full, or the disk is nearly full, new jobs and uploads also answer 503 with busy. Retry after the Retry-After wait.