Errors - lyrcs.ai

All error responses follow a consistent JSON shape:

{
  "error": "validation_error",
  "message": "language field is required",
  "code": "VAL_001"
}

Error reference

HTTP	`error`	`code`	Trigger
400	`validation_error`	`VAL_001`	Missing required field, unsupported language, invalid `audio_url`, batch with 0 or >20 jobs, malformed JSON body
401	`unauthorized`	`AUTH_001`	Missing or malformed `Authorization` header, invalid API key, inactive key, expired key
402	`insufficient_credits`	`PAY_001`	Organisation credit balance is 0 or below — contact your administrator
402	`insufficient_credits`	`PAY_002`	Your plan does not include alignment. Submit with `align=false` for transcript-only output, or ask your administrator to upgrade
404	`not_found`	`NOT_001`	Job or batch not found; job belongs to a different organisation; unknown LRC/SRT type in download URL
413	`payload_too_large`	`VAL_002`	The uploaded audio exceeds the request body limit. Use `audio_url` instead — see below
409	`idempotency_in_progress`	`IDEM_001`	A request with this `Idempotency-Key` is still being processed. Retryable after a short wait
409	`idempotency_key_reused`	`IDEM_002`	This `Idempotency-Key` was already used for a different request. Use a new key
409	`not_transcribed`	`ALN_001`	`POST /jobs/{id}/align` before transcription finished
409	`awaiting_review`	`ALN_002`	`POST /jobs/{id}/align` on a job held at the transcript review gate. Approve it instead
409	`realign_failed`	`ALN_003`	Re-alignment unavailable or produced no usable result. Existing timings are unchanged
409	`alignment_in_progress`	`ALN_004`	Alignment is already running for this job
422	`no_audio`	`ALN_005`	The job has no stored audio to align against
409	`not_held_for_review`	`APR_001`	`POST /jobs/{id}/approve` on a job that is not waiting for review
400	`invalid_request`	`APR_002`	`lines` / `transliterated_lines` was not an array of strings, or was empty
409	`api_approval_disabled`	`APR_003`	The job was submitted with `review_delivery: "link"`; approve it from the review page
409	`scripts_out_of_sync`	`APR_005`	`lines` and `transliterated_lines` would have different lengths. The scripts are position-parallel — send both
502	`release_failed`	`APR_004`	Edits saved but the job could not be released. Retry — the approval was rolled back
409	`no_webhook_url`	`HOOK_001`	Replay requested for a job submitted without a `webhook_url`
409	`not_complete`	`HOOK_002`	`job.complete` replay requested before the job finished
409	`no_review_pending`	`HOOK_003`	`job.awaiting_review` replay requested for a job with no review link
409	`review_expired`	`HOOK_004`	The review link has expired; contact support for a new one
404	`not_found`	`HOOK_005`	Dead-letter replay requested for an id that does not exist or belongs to another organisation
409	`already_resolved`	`HOOK_006`	Dead-letter replay requested for an entry already cleared
409	`line_count_locked`	`REV_001`	Lines cannot be added or removed on this job, because its timings cannot be re-derived
429	`rate_limit_exceeded`	`RATE_001`	Any rate limit window exhausted
410	`endpoint_withdrawn`	`GONE_001`	The endpoint has been withdrawn. The message names what to use instead
500	`storage_error`	`SRV_001`	We could not store your audio. Retryable

VAL_002 is the most common first-integration failure. A direct file upload is capped at roughly 4.5 MB by the serverless request body limit, which most real audio exceeds. Submit audio_url instead — there is no size limit on that path, because we fetch the file server-side.

PAY_001 and PAY_002 are different problems. PAY_001 means you are out of credits. PAY_002 means your plan does not cover the feature you asked for, and buying credits will not fix it.

Retired codes

Code	Status
`AUTH_002`	No longer returned. Its only source was `POST /v1/align`, which has been withdrawn. Existing handling for it is harmless and can be removed.

404 is returned for cross-organisation access attempts as well as genuinely missing resources. This prevents enumeration of other organisations’ job IDs.

Of these, RATE_001, SRV_001 and IDEM_001 are worth retrying automatically. Everything else describes something a retry cannot change.

IDEM_002 is a bug in your code, not a transient failure. It means one Idempotency-Key was sent with two different request bodies. Retrying will not help; generate a fresh key per submission. We refuse rather than replaying the first result, because replaying would silently drop the second song.

Rate limit errors — 429

Standard (single job):

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: minute limit reached",
  "code": "RATE_001",
  "retry_after": 60
}

Batch variant — includes jobs_requested:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: minute limit would be exceeded by this batch",
  "code": "RATE_001",
  "retry_after": 60,
  "jobs_requested": 15
}

The retry_after field is the number of seconds to wait before retrying. A Retry-After header with the same value is also included.

Rate limit headers

Every authenticated response includes the rate limit state for the budget that request drew from. Submissions and reads are metered separately, so the numbers differ depending on which you called.

Header	Value
`X-RateLimit-Meter`	`submit` or `read` — which budget this request used
`X-RateLimit-Limit-Minute`	Ceiling for that meter this minute
`X-RateLimit-Limit-Hour`	Ceiling for that meter this hour
`X-RateLimit-Limit-Day`	Ceiling for that meter today
`X-RateLimit-Remaining-Minute`	Remaining in the current minute
`X-RateLimit-Remaining-Hour`	Remaining in the current hour
`X-RateLimit-Remaining-Day`	Remaining today

X-RateLimit-Meter tells you which set of numbers you are looking at. A GET /jobs/{id} reports your read headroom; only a submission reports the budget that governs how many songs you can send. See Default rate limits for the ceilings. Check X-RateLimit-Remaining-Minute on a submission before sending a large batch to confirm you have enough headroom. Rejected requests do not consume quota.

Validation errors — 400

Common triggers for VAL_001:

language field missing or not matching any entry in GET /api/v1/languages (case-sensitive)
Neither file nor audio_url provided to POST /transcribe
audio_url is not a valid HTTPS URL
Batch body is not an array or { jobs: [...] } object
Batch jobs array has 0 or more than 20 entries
Individual batch job missing audio_url or language
Invalid audio MIME type or file extension on file upload

402 — Insufficient Credits

{
  "error": "insufficient_credits",
  "message": "No credits remaining — contact your administrator",
  "code": "PAY_001"
}

Contact your account administrator or email support@lyrcs.ai to add credits.

Download endpoints — 202, 409 and 404

The download endpoints (/download/lrc/*, /download/srt/*, /download/words/*) distinguish three cases, and the difference is what tells a client whether to retry:

Code	Meaning	What to do
`202`	The job is still running	Retry later
`409`	The file will never exist — the job failed, or the output was never requested	Stop polling
`404`	The job doesn’t exist, or belongs to another account	Stop

{ "status": "processing", "stage": "aligning" }

409 responses carry a code: JOB_001 for a failed job (with stage and message describing what went wrong) and JOB_002 for output that was never requested, such as calling an LRC download on an align=false job. Prefer polling GET /jobs/{id} and fetching downloads once it reports status: "complete".

Job failure codes

Code	HTTP	Meaning
`JOB_001`	409	The job failed. `stage` is `transcription` or `alignment`.
`JOB_002`	409	The requested output was never generated because it wasn’t requested at submission.

Neither is retryable on the same job. JOB_001 at the transcription stage may be worth resubmitting; JOB_002 means resubmitting with different flags.

​Error reference

​Retired codes

​Rate limit errors — 429

​Rate limit headers

​Validation errors — 400

​402 — Insufficient Credits

​Download endpoints — 202, 409 and 404

​Job failure codes

Error reference

Retired codes

Rate limit errors — 429

Rate limit headers

Validation errors — 400

402 — Insufficient Credits

Download endpoints — 202, 409 and 404

Job failure codes