Skip to main content
Every error returns a consistent JSON envelope with the matching HTTP status code.

​
Error envelope

{
  "statusCode": 404,
  "error": "EntityNotFoundException",
  "message": "Voice with id: 00000000-0000-0000-0000-000000000000 does not exist!"
}
FieldDescription
statusCodeHTTP status code, echoed in the body.
errorMachine-readable error class. Branch on this, not on the message text.
messageHuman-readable explanation.
Match on statusCode and error, not on message. Message strings may be refined over time.

​
Status codes

StatuserrorMeaning
400BadRequestExceptionThe request was malformed.
401UnauthorizedExceptionMissing, invalid, or expired API key, or a disallowed origin.
403InsufficientCreditsExceptionNot enough credits to complete the request.
403HTTPExceptionThe product is not available on your plan.
404EntityNotFoundExceptionThe voice, inference, or resource does not exist.
422ValidationExceptionA field failed validation or a business rule (e.g. text length, voice not ready).
422RequestValidationErrorThe request body or query failed schema validation.
429HTTPExceptionToo many concurrent requests for your plan.
500ProcessExceptionAn unexpected server error. Charged credits are refunded.

​
Common errors

​
Authentication (401)

MessageCause
No API key or user credentials providedThe chariotai-api-key header is missing.
Invalid API Key or user credentialsThe key is unknown or malformed.
API Key expiredThe key has passed its expiry.
Unauthorized request!A public key was used from a non-allowlisted origin.

​
Text to speech

StatusMessageCause
404Voice with id: ... does not exist!Unknown voice_id.
422Voice ... is not ready for TTS yet!The voice is not yet available for synthesis.
422Input text of length N is more than maximum character count of 500 characters!Text over the 500-character limit.
403Workspace has N credits; needs MNot enough credits.
429Concurrent request limit exceeded (N) for tts.standard on the current planOver your plan’s concurrency limit.

​
Handling errors

Confirm the chariotai-api-key header is present and the key is active. For public keys, confirm the request origin is on the key’s allowlist. See Authentication.
InsufficientCreditsException means you’re out of credits, check GET /v1/credits. A plan HTTPException means the product isn’t on your plan.
Validate voice_id is a real UUID, keep text within 1 to 500 characters, and confirm the voice is available before using it.
You’ve hit your plan’s concurrency limit. Retry with exponential backoff and jitter, and cap your in-flight requests. See Rate limits & concurrency.
An unexpected server error. Any credits charged for the failed request are refunded. Retry after a short delay; if it persists, contact support with the Inference-Id.