{"schema_version":1,"actions":[{"code":"UNAUTHENTICATED","retryable":false,"action":"Check token expiry or revocation. Reconnect through the client; never print credentials.","http_statuses":[401]},{"code":"SESSION_REQUIRED","retryable":false,"action":"This action requires the account owner's browser session. Direct them to the signed-in web app.","http_statuses":[403]},{"code":"TOKEN_SCOPE_REQUIRED","retryable":false,"action":"Show details.required_scope to the owner. Do not broaden permissions automatically.","http_statuses":[403]},{"code":"SIGNUP_REQUIRED","retryable":false,"action":"The owner must finish account enrollment in the web app.","http_statuses":[403]},{"code":"HUMAN_VERIFICATION_REQUIRED","retryable":false,"action":"The owner must complete one-time human verification in the web app. Never automate or bypass it.","http_statuses":[403]},{"code":"TRIAL_ACTIVATION_REQUIRED","retryable":false,"action":"Activate the account allowance once in the web app.","http_statuses":[403]},{"code":"TRIAL_PAUSED","retryable":false,"action":"The free offer is paused. Show the available plans to the owner without changing plans.","http_statuses":[403]},{"code":"QUOTA_EXCEEDED","retryable":false,"action":"Check account usage and reserved credits. Show details.upgrade.billing_url or wait for the reset; do not purchase anything.","http_statuses":[402]},{"code":"SEARCH_QUOTA_EXCEEDED","retryable":false,"action":"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.","http_statuses":[402]},{"code":"VIDEO_TOO_LONG","retryable":false,"action":"Compare details.duration_minutes with details.limit_minutes. Show the available upgrade; do not resubmit the same source.","http_statuses":[422]},{"code":"PLAN_FEATURE_REQUIRED","retryable":false,"action":"Show the plan requirement and details.upgrade.billing_url to the account owner.","http_statuses":[403]},{"code":"CAPTIONS_UNAVAILABLE","retryable":false,"action":"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.","http_statuses":[422]},{"code":"ASR_REQUIRES_UPGRADE","retryable":false,"action":"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.","http_statuses":[403]},{"code":"TRANSCRIPTION_NOT_ALLOWED","retryable":false,"action":"Fresh audio transcription is not supported. Legacy transcription controls do not enable it; use usable saved source, captions or authorized supplied text instead.","http_statuses":[422]},{"code":"MAX_CREDITS_EXCEEDED","retryable":false,"action":"The ceiling is invalid or below the required charge. Ask the owner before increasing it; preserve the original job or request.","http_statuses":[402,422]},{"code":"DUPLICATE_ACTIVE_JOB","retryable":false,"action":"Find and follow the existing job rather than submitting another copy.","http_statuses":[409]},{"code":"RATE_LIMITED","retryable":true,"action":"Honor Retry-After and the existing job's polling hint. Retry an uncertain POST only with the exact original body and idempotency key.","http_statuses":[429]},{"code":"IDEMPOTENCY_CONFLICT","retryable":false,"action":"The key belongs to another request body. Recover the original job or use a new key only for newly authorized work.","http_statuses":[409]},{"code":"SOURCE_UNAVAILABLE","retryable":false,"action":"Explain the unavailable or incomplete source. Accept complete source text if the user supplies it; never pretend missing content was read.","http_statuses":[422]},{"code":"UNSUPPORTED_CONTENT","retryable":false,"action":"Explain the unsupported source type and request a supported source or complete text.","http_statuses":[422]},{"code":"VIDEO_PRIVATE","retryable":false,"action":"The source requires access the service does not have. Do not request passwords or private cookies.","http_statuses":[422]},{"code":"VIDEO_MEMBERS_ONLY","retryable":false,"action":"Members-only video is unavailable. Request authorized source text instead.","http_statuses":[422]},{"code":"VIDEO_AGE_RESTRICTED","retryable":false,"action":"Age-restricted video is unavailable. Request authorized source text instead.","http_statuses":[422]},{"code":"VIDEO_UNAVAILABLE","retryable":false,"action":"The source may be removed or region restricted. Do not repeatedly resubmit.","http_statuses":[422]},{"code":"LIVE_NOT_SUPPORTED","retryable":false,"action":"Wait until the live stream has ended before requesting a new analysis.","http_statuses":[422]},{"code":"NO_SPEECH_DETECTED","retryable":false,"action":"Explain that usable speech was not detected. Do not invent a transcript.","http_statuses":[422]},{"code":"FEATURE_DISABLED","retryable":false,"action":"This feature is off on this deployment. Explain that it is unavailable; do not retry automatically.","http_statuses":[422,503]},{"code":"PLATFORM_BLOCKED","retryable":false,"action":"The source platform is blocking retrieval. Try later only when the user authorizes a new attempt.","http_statuses":[503]},{"code":"SUBTITLE_PARSE_ERROR","retryable":false,"action":"The captions could not be read. Explain the source failure; do not invent missing text or automatically start another job.","http_statuses":[422]},{"code":"TRANSCRIPT_TOO_LONG","retryable":false,"action":"The available transcript exceeds the supported limit. Ask the user to select a shorter source or supply a bounded excerpt.","http_statuses":[422]},{"code":"INVALID_URL","retryable":false,"action":"Ask for a supported YouTube or public X link, or complete supplied text. Do not guess the source.","http_statuses":[400]},{"code":"UNSUPPORTED_PLATFORM","retryable":false,"action":"Use a supported source or complete text provided by the user. Do not substitute an unrelated link.","http_statuses":[400]},{"code":"VALIDATION_ERROR","retryable":false,"action":"Correct the rejected fields using the documented schema; do not raise a spending ceiling without user authorization.","http_statuses":[409,422]},{"code":"NOT_FOUND","retryable":false,"action":"Check the existing job and its own source IDs. Do not guess other IDs.","http_statuses":[404]},{"code":"ACCOUNT_UNAVAILABLE","retryable":false,"action":"Stop and direct the account owner to support. Rotating credentials or creating another account does not resolve account suspension.","http_statuses":[403]},{"code":"SPEND_LIMIT_REACHED","retryable":false,"action":"The service or account provider budget refused this call. Stop automatic retries; preserve the job/key and wait for capacity or owner support guidance.","http_statuses":[503]},{"code":"SOURCE_FETCH_FAILED","retryable":false,"action":"The source provider could not complete retrieval. Preserve the request/key and explain the failure; do not start new analyses automatically.","http_statuses":[503]},{"code":"BILLING_UNAVAILABLE","retryable":true,"action":"Billing reconciliation is temporarily unavailable. Use bounded retries for the same read or stable-key request; do not buy credits or resubmit another job.","http_statuses":[503]},{"code":"BILLING_CONFIGURATION_ERROR","retryable":false,"action":"Stop retries and direct the account owner to support for billing configuration review.","http_statuses":[503]}],"docs_url":"https://tldw.sh/docs/errors.md"}