Errors & status codes

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!"
}

Field	Description
`statusCode`	HTTP status code, echoed in the body.
`error`	Machine-readable error class. Branch on this, not on the message text.
`message`	Human-readable explanation.

Match on statusCode and error, not on message. Message strings may be refined over time.

Status codes

Status	`error`	Meaning
`400`	`BadRequestException`	The request was malformed.
`401`	`UnauthorizedException`	Missing, invalid, or expired API key.
`403`	`InsufficientCreditsException`	Not enough credits to complete the request.
`403`	`HTTPException`	The product is not available on your plan.
`404`	`EntityNotFoundException`	The voice, inference, or resource does not exist.
`422`	`ValidationException`	A field failed validation or a business rule (e.g. text length, voice not ready).
`422`	`RequestValidationError`	The request body or query failed schema validation.
`429`	`HTTPException`	Too many concurrent requests for your plan.
`500`	`ProcessException`	An unexpected server error. Charged credits are refunded.

Common errors

Authentication (401)

Message	Cause
`No API key or user credentials provided`	The `chariotai-api-key` header is missing.
`Invalid API Key or user credentials`	The key is unknown or malformed.
`API Key expired`	The key has passed its expiry.

Text to speech

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

Handling errors

401: re-check your key and header

Confirm the chariotai-api-key header is present and the key is active. See Authentication.

403: top up or upgrade

InsufficientCreditsException means you’re out of credits, check GET /v1/credits. A plan HTTPException means the product isn’t on your plan.

422: fix the input

Validate voice_id is a real UUID, keep text within 1 to 500 characters, and confirm the voice is available before using it.

429: back off and retry

You’ve hit your plan’s concurrency limit. Retry with exponential backoff and jitter, and cap your in-flight requests. See Rate limits & concurrency.

500: safe to retry

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.

Get started

Text to speech

Resources

Errors & status codes

Error envelope

Status codes

Common errors

Authentication (401)

Text to speech

Handling errors

​Error envelope

​Status codes

​Common errors

​Authentication (401)

​Text to speech

​Handling errors

Error envelope

Status codes

Common errors

Authentication (401)

Text to speech

Handling errors