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
403	`forbidden`	`AUTH_002`	API key does not have permission to access this endpoint — contact your account administrator
404	`not_found`	`NOT_001`	Job or batch not found; job belongs to a different organisation; unknown LRC/SRT type in download URL
429	`rate_limit_exceeded`	`RATE_001`	Any rate limit window exhausted

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

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 current rate limit state:

Header	Value
`X-RateLimit-Limit-Minute`	`10`
`X-RateLimit-Limit-Hour`	`100`
`X-RateLimit-Limit-Day`	`1000`
`X-RateLimit-Remaining-Minute`	Requests remaining in the current minute
`X-RateLimit-Remaining-Hour`	Requests remaining in the current hour
`X-RateLimit-Remaining-Day`	Requests remaining today

Check X-RateLimit-Remaining-Minute before submitting a large batch to confirm you have enough headroom.

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

​Rate limit errors — 429

​Rate limit headers

​Validation errors — 400

​402 — Insufficient Credits

​Download endpoints — 202, 409 and 404

​Job failure codes

Error reference

Rate limit errors — 429

Rate limit headers

Validation errors — 400

402 — Insufficient Credits

Download endpoints — 202, 409 and 404

Job failure codes