Errors

Base URL https://api.suisse-speech.ch/v1 · X-API-Key

Every error has the same shape:

{"error":{"code":"tts.unknown_voice","message":"Unknown voice.","request_id":"req_…","detail":null}}

code is stable and safe to branch on.
message is fixed text, not a description of what went wrong internally.
detail appears only for problems in your request that need explaining (chiefly markup) and is capped at 400 characters.
request_id is what to quote in a support request.

GET /capabilities returns the full list under errors. The families:

prefix	when
`tts.*`	synthesis
`stt.*`	recognition

code	HTTP	retry?
`*.invalid_request`, `tts.unknown_voice`, `tts.unknown_language`, `tts.unsupported_format`, `tts.invalid_speed`, `tts.invalid_ssml`	400	no: fix the request
`*.unauthenticated`	401	no
`*.forbidden`	403	no
`tts.text_too_long`, `stt.audio_too_large`	413	no
`*.rate_limited`	429	yes, after `Retry-After`
`*.entitlement_exhausted`	429	no: the free minutes or the credit are used up
`*.capacity`	429	yes, after `Retry-After`
`*.plan_limit_reached`	429	not by itself: reduce parallelism or raise the limit
`*.unavailable`	503	yes, with backoff
`*.timeout`	504	yes
`*.internal_error`, `tts.encode_failed`	500	once, then contact us

Four different things answer with 429, and only error.code tells them apart. An HTTP client that reports only the status line hides this distinction, so log the response body of every 429.

Failures are deliberately uninformative about their cause. A credential problem on our side and a fault on our side both surface as unavailable. This is intentional: the error surface does not describe our internals.

Recommended client behaviour: retry 503/504 with exponential backoff and jitter, honour Retry-After exactly on 429, and never retry a 4xx other than those two without changing the request.

What will not change without notice

Voice identifiers and what they sound like.
Error code values.
The realtime frame vocabulary.
The meaning of the metering unit.

Things that will change and should be read at runtime: the voice list, the language list, formats, limits and capacity figures. GET /capabilities is the contract for those.