HTTP errors
We use standard HTTP status codes to indicate the success or failure of a request:
- 400 -
invalid_request_error: The request is malformed or contains invalid content. - 401 -
authentication_error: The API key is missing or unrecognized. - 402 -
payment_required_error: Your plan is out of credits or your subscription is past due. Check your payment details in Playground. - 403 -
permission_error: The API key doesn't have permission to access this resource. - 404 -
not_found_error: The requested resource doesn't exist. - 429 -
rate_limit_error: Your account has hit a rate limit. - 5xx -
internal_server_error: Something went wrong on our end. Retry with exponential backoff.
Error shape
Errors are always returned as JSON, with a top-level error object that always includes a type and message value.
The response also includes a request_id field for easier tracking and debugging. For example:
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "Voice 'foo' not found."
},
"request_id": "req_X7cMY9WUno4rzYSUmuigg6"
}Request id
Every API response includes a unique request-id header. This header contains a value such as req_K5kw6MKtCL83A9bNGcrV3w.
When contacting support about a specific request, include this ID to help quickly resolve your issue.
The official SDKs provide this value as a property on top-level response objects, containing the value of the request-id header:
from lmnt import Lmnt
client = Lmnt()
voice_response = client.voices.retrieve('leah')
print(voice_response.request_id)Streaming errors
When you consume a streaming response — binary audio chunks from POST /v1/ai/speech/bytes or messages from a speech session WebSocket — an error that occurs after the initial 200 (or successful WebSocket handshake) won't be delivered as a JSON error body.
- For the streaming bytes endpoint, we terminate the connection and reset the underlying HTTP/2 stream.
- For the WebSocket session, we send a close frame with a status code and reason describing the failure.
Treat an early end-of-stream as a potential mid-flight error rather than a clean completion.
Long requests
Some networks drop idle TCP connections after a variable period, which can cause long-lived non-streaming requests to fail without a response. To generate a large amount of speech, split it into smaller requests or use one of the streaming endpoints, which deliver speech continuously and keep the connection active.