Developer platform

Error codes

REST, NDJSON and WebSocket can use different error shapes. Handle them according to the contract of the product you are calling.

On this page

Error shapes
Loly 3.5
Loli 2.0
Retrying

Error shapes

Loly 3.5, REST

JSON

{
  "ok": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Not enough quota remaining"
  }
}

Check ok first, then read error.code. Branch on code rather than message, because the wording may change.

Loli 2.0, REST

The STT surface has two error shapes. A failure raised by the public proxy uses the envelope; a failure returned by the STT service itself may have no ok field. A client has to accept both.

JSON

// Raised by the public proxy, before transcription starts
{ "ok": false, "error": { "code": "BAD_REQUEST", "message": "Error description" } }

// Raised by the STT service, no ok field
{ "error": { "code": "bad_request", "message": "Error description" } }

NDJSON and WebSocket

An error can also arrive inside the stream, after the HTTP response or the WebSocket handshake has already succeeded. Always check for an event with type error.

Loly 3.5

Code	HTTP	Meaning
`INVALID_API_KEY`	401, 403	Key missing, wrong, inactive, revoked, expired, of the wrong type, or lacking the scope.
`PERMISSION_DENIED`	403	A valid account key has its required TTS, STT, audio-library or API-key usage switch turned off.
`VOICE_ID_REQUIRED`	400	An account-key TTS request omitted voice_id.
`VOICE_NOT_ALLOWED`	403	The requested voice does not exist, is outside the account-key scope, or conflicts with the voice key binding.
`ACCOUNT_DISABLED`	403	The account behind the enrollment key is disabled.
`VOICE_NOT_FOUND`	404	The voice bound to the voice key no longer exists.
`VALIDATION_FAILED`	400	A voice enrollment field is invalid. Read error.details[].
`VOICE_LIMIT_REACHED`	403	The account has reached the public enrollment ceiling.
`RATE_LIMITED`	429	Enrollments are arriving too fast. Read the Retry-After header.
`ENROLLMENT_FAILED`	503	Voice enrollment could not be completed.
`BAD_REQUEST`	400	A request field is missing or invalid.
`TEXT_TOO_LONG`	400	Batch text exceeds 5,000 characters.
`INVALID_LANGUAGE`	400	language is not auto, a catalog code, or a catalog name.
`INVALID_FORMAT`	400	format is not exactly wav or mp3.
`KEY_CREDIT_EXCEEDED`	403	The credential has exhausted its own lifetime character ceiling.
`QUOTA_EXCEEDED`	403	Not enough allowance remaining. Read GET /api/v1/usage.
`VOICE_FEATURE_UNAVAILABLE`	503	The selected clone voice's feature or reference audio could not be loaded; the model was not called.
`BACKEND_ERROR`	4xx, 5xx	The generation backend refused the request or failed.
`NOT_FOUND`	404	The allowance record or the resource was not found.
`INTERNAL_ERROR`	500	An unclassified server fault.

Over WebSocket, an error arrives as a JSON event rather than as a REST envelope.

Loli 2.0

Code	HTTP	Meaning
`BAD_REQUEST, bad_request`	400	Invalid multipart body, audio, language or duration.
`INVALID_API_KEY, unauthorized`	401	Key missing, wrong or revoked.
`INVALID_API_KEY, FORBIDDEN`	403	Key expired or lacking the scope.
`KEY_CREDIT_EXCEEDED`	403	The STT key exhausted its lifetime transcript-character ceiling.
`QUOTA_EXCEEDED`	403	The account has no STT quota left to start a request.
`FILE_TOO_LARGE`	413	The upload exceeds 100 MiB.
`unsupported_audio_format`	415	The container or encoding is not supported.
`stt_upstream_error`	502	The transcription engine failed.
`SERVICE_NOT_CONFIGURED, STT_UNAVAILABLE, model_not_ready`	503	The service is unconfigured, unreachable or not ready yet.
`INTERNAL_ERROR, internal_error`	500	An unclassified server fault.

Retrying

Retry 500, 502 and 503 only, with exponential backoff. A 4xx is caused by the request, so replaying it unchanged fails the same way.

The allowance is deducted up front

The allowance is deducted when the request is accepted, before synthesis runs. A request that fails inside the backend has already spent it, so blind retries consume the allowance faster than expected.