Guides

Error Reference

All SAUTI API errors use the RFC 7807 Problem Detail format. This page lists every error code, its HTTP status, and how to handle it.

Error format

Every error response is application/problem+json (RFC 7807). The body always contains type, title, status, and detail. The instance field is included where available.

json

{
  "type": "https://sauti.finiflowlabs.com/errors/{error_code}",
  "title": "Human-readable error title",
  "status": 400,
  "detail": "Specific explanation of what went wrong.",
  "instance": "/v1/text-to-speech/{voice_id}"
}

Error codes

HTTP Status	Error Code	Meaning	Action
`400`	`invalid_request`	Request body is malformed, missing a required field, or contains an unrecognised parameter.	Fix the request body and retry.
`401`	`unauthorized`	API key is missing, malformed, or has been revoked.	Check that the `xi-api-key` header is set correctly. Request a new key if needed.
`409`	`job_not_complete`	Attempted to download audio for a job that has not finished processing.	Poll the job status endpoint until `status` is `succeeded`, then retry the download.
`413`	`payload_too_large`	Request body exceeds the maximum allowed size.	Reduce the size of the request payload.
`422`	`unprocessable_content`	The request was well-formed but failed validation — e.g. text too long or unsupported voice_id.	Read the `detail` field and adjust the input.
`429`	`rate_limit_exceeded`	Per-minute request rate exceeded.	Wait the number of seconds in the `Retry-After` header, then retry. See Rate Limits.
`500`	`internal_error`	An unexpected error on the server side.	Retry with exponential backoff. If the error persists, contact hello@finiflowlabs.com.

Examples

400 Invalid Request

json

{
  "type": "https://sauti.finiflowlabs.com/errors/invalid_request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Request body is malformed or missing required field 'text'.",
  "instance": "/v1/text-to-speech/sauti-swahili-v1"
}

401 Unauthorized

json

{
  "type": "https://sauti.finiflowlabs.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is missing or invalid."
}

409 Job Not Complete

json

{
  "type": "https://sauti.finiflowlabs.com/errors/job_not_complete",
  "title": "Conflict",
  "status": 409,
  "detail": "Job has not completed yet. Poll the status endpoint before downloading audio.",
  "instance": "/v1/tts/jobs/job_abc123/audio"
}

413 Payload Too Large

json

{
  "type": "https://sauti.finiflowlabs.com/errors/payload_too_large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "Request body exceeds the maximum allowed size."
}

429 Rate Limit Exceeded

json

{
  "type": "https://sauti.finiflowlabs.com/errors/rate_limit_exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 10 requests per minute for synthesis. Try again shortly."
}

500 Internal Server Error

json

{
  "type": "https://sauti.finiflowlabs.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support."
}