# Errors and recovery Errors use an error envelope with code, message, details and request_id when available. Keep the reference ID for support; never attach tokens or credentials. - **UNAUTHENTICATED** — retryable: false. Check token expiry or revocation. Reconnect through the client; never print credentials. - **SESSION_REQUIRED** — retryable: false. This action requires the account owner's browser session. Direct them to the signed-in web app. - **TOKEN_SCOPE_REQUIRED** — retryable: false. Show details.required_scope to the owner. Do not broaden permissions automatically. - **SIGNUP_REQUIRED** — retryable: false. The owner must finish account enrollment in the web app. - **HUMAN_VERIFICATION_REQUIRED** — retryable: false. The owner must complete one-time human verification in the web app. Never automate or bypass it. - **TRIAL_ACTIVATION_REQUIRED** — retryable: false. Activate the account allowance once in the web app. - **TRIAL_PAUSED** — retryable: false. The free offer is paused. Show the available plans to the owner without changing plans. - **QUOTA_EXCEEDED** — retryable: false. Check account usage and reserved credits. Show details.upgrade.billing_url or wait for the reset; do not purchase anything. - **SEARCH_QUOTA_EXCEEDED** — retryable: false. The plan's monthly X video searches are used up; the count resets when the next billing period starts. Show details.upgrade.billing_url to the owner when present; do not retry or purchase anything. - **VIDEO_TOO_LONG** — retryable: false. Compare details.duration_minutes with details.limit_minutes. Show the available upgrade; do not resubmit the same source. - **PLAN_FEATURE_REQUIRED** — retryable: false. Show the plan requirement and details.upgrade.billing_url to the account owner. - **CAPTIONS_UNAVAILABLE** — retryable: false. No accessible captions or usable saved transcript were found. The failed job releases its hold without a processing-credit charge. Stop or accept authorized source text; do not resubmit automatically. Fresh audio transcription is not supported; legacy controls do not enable it. - **ASR_REQUIRES_UPGRADE** — retryable: false. Fresh audio transcription is not supported on this service. Use usable saved source, captions or authorized supplied text; upgrading or changing legacy controls does not enable audio. - **TRANSCRIPTION_NOT_ALLOWED** — retryable: false. Fresh audio transcription is not supported. Legacy transcription controls do not enable it; use usable saved source, captions or authorized supplied text instead. - **MAX_CREDITS_EXCEEDED** — retryable: false. The ceiling is invalid or below the required charge. Ask the owner before increasing it; preserve the original job or request. - **DUPLICATE_ACTIVE_JOB** — retryable: false. Find and follow the existing job rather than submitting another copy. - **RATE_LIMITED** — retryable: true. Honor Retry-After and the existing job's polling hint. Retry an uncertain POST only with the exact original body and idempotency key. - **IDEMPOTENCY_CONFLICT** — retryable: false. The key belongs to another request body. Recover the original job or use a new key only for newly authorized work. - **SOURCE_UNAVAILABLE** — retryable: false. Explain the unavailable or incomplete source. Accept complete source text if the user supplies it; never pretend missing content was read. - **UNSUPPORTED_CONTENT** — retryable: false. Explain the unsupported source type and request a supported source or complete text. - **VIDEO_PRIVATE** — retryable: false. The source requires access the service does not have. Do not request passwords or private cookies. - **VIDEO_MEMBERS_ONLY** — retryable: false. Members-only video is unavailable. Request authorized source text instead. - **VIDEO_AGE_RESTRICTED** — retryable: false. Age-restricted video is unavailable. Request authorized source text instead. - **VIDEO_UNAVAILABLE** — retryable: false. The source may be removed or region restricted. Do not repeatedly resubmit. - **LIVE_NOT_SUPPORTED** — retryable: false. Wait until the live stream has ended before requesting a new analysis. - **NO_SPEECH_DETECTED** — retryable: false. Explain that usable speech was not detected. Do not invent a transcript. - **FEATURE_DISABLED** — retryable: false. This feature is off on this deployment. Explain that it is unavailable; do not retry automatically. - **PLATFORM_BLOCKED** — retryable: false. The source platform is blocking retrieval. Try later only when the user authorizes a new attempt. - **SUBTITLE_PARSE_ERROR** — retryable: false. The captions could not be read. Explain the source failure; do not invent missing text or automatically start another job. - **TRANSCRIPT_TOO_LONG** — retryable: false. The available transcript exceeds the supported limit. Ask the user to select a shorter source or supply a bounded excerpt. - **INVALID_URL** — retryable: false. Ask for a supported YouTube or public X link, or complete supplied text. Do not guess the source. - **UNSUPPORTED_PLATFORM** — retryable: false. Use a supported source or complete text provided by the user. Do not substitute an unrelated link. - **VALIDATION_ERROR** — retryable: false. Correct the rejected fields using the documented schema; do not raise a spending ceiling without user authorization. - **NOT_FOUND** — retryable: false. Check the existing job and its own source IDs. Do not guess other IDs. - **ACCOUNT_UNAVAILABLE** — retryable: false. Stop and direct the account owner to support. Rotating credentials or creating another account does not resolve account suspension. - **SPEND_LIMIT_REACHED** — retryable: false. The service or account provider budget refused this call. Stop automatic retries; preserve the job/key and wait for capacity or owner support guidance. - **SOURCE_FETCH_FAILED** — retryable: false. The source provider could not complete retrieval. Preserve the request/key and explain the failure; do not start new analyses automatically. - **BILLING_UNAVAILABLE** — retryable: true. Billing reconciliation is temporarily unavailable. Use bounded retries for the same read or stable-key request; do not buy credits or resubmit another job. - **BILLING_CONFIGURATION_ERROR** — retryable: false. Stop retries and direct the account owner to support for billing configuration review. Do not automatically retry terminal processing failures: retries can consume attempts and provider cost. Read the account and source limits first. For transient HTTP 429/503 while reading status, use bounded backoff and Retry-After. Never follow a returned status/result URL to another origin with your bearer token. Human onboarding: https://tldw.sh/agents OpenAPI: https://tldw.sh/openapi.json Machine pricing: https://tldw.sh/pricing.md Actionable errors: https://tldw.sh/docs/errors.json