Get startedErrors and limits

Errors and limits

Every status code and message the API sends, what to do about it, and the limits that apply.

HTTP errors

Errors carry a status code and a JSON body with detail. detail is usually a string; account and billing refusals send an object with code and message instead. Read both:

{ "detail": "audio shorter than 0.05 s" }

{
  "detail": {
    "code": "…",
    "message": "…",
    "top_up_url": "https://console.p99lab.com/dashboard/billing",
    "plans_url": "https://console.p99lab.com/dashboard/billing"
  }
}

top_up_url and plans_url come with a 402 for a used-up balance. A 429 or 503 from billing carries a Retry-After header.

Status	detail	What to do
400	`empty body`	Send the audio as the body or as the `file` part.
400	`multipart body needs a "file" part`	Name the form part `file`.
400	`could not read the audio`	Send a supported, undamaged audio or video file.
400	`audio shorter than 0.05 s`	Send longer audio.
400	`language must be en`	Send `language=en` or leave it out.
401	`missing API key` or `unknown API key`	Check the header and the key.
402	Balance used up, or a renewal payment is overdue	Choose a plan or pay the open invoice in the console under Billing.
413	`file larger than 600 MB`	Split the recording.
413	`audio longer than 4 hours` (`2 hours` on self-serve accounts)	Split the recording.
429	`too many parallel requests for this key (limit 8)`	Wait for a request to finish, or spread work over more keys.
429	The key reached its daily audio limit	It resets at midnight Pacific time.
429	`allowance for this key is used up`	Evaluation keys with a fixed allowance: write to us for more hours.
503	`daily capacity reached; try again after 00:00 UTC`	Retry after the time in `Retry-After`.
503	`billing is unavailable; retry shortly`	Retry after the time in `Retry-After`.
5xx	A problem on our side	Retry with backoff: 1 s, then 2 s, then 4 s. A failed request is not charged.

Stream errors

On a stream, an error arrives as one message and the socket closes:

{ "type": "error", "message": "sample_rate must be 8000, 16000, 24000 or 48000" }

Account and billing errors add code (402, 429 or 503); a 402 also carries top_up_url and plans_url, and a stream stopped mid-session carries audio_seconds.

message	What to do
`first message must be a JSON config, within 10 s`	Send the configuration as a JSON text message right after connecting.
`unknown API key`	Check the key.
`language must be en`	Send `"language": "en"` or leave it out.
`sample_rate must be 8000, 16000, 24000 or 48000`	Resample on your side, or configure the rate you send.
`endpoint_ms and partial_ms must be numbers`	Send numbers.
`turn_detection must be true or false`	Send a JSON boolean.
`audio message larger than 64 KB`	Send smaller chunks.
`audio arrived faster than it can be processed`	Send audio at real-time speed; more than 5 s of unprocessed audio ends the session.
`too much speech waiting for transcription (server busy)`	Reconnect after a short wait.
`server busy: too much audio waiting for transcription`	Reconnect after a short wait.
`too many parallel streams for this key (limit 4)`, code 429	Close a stream, or use another key.
Balance used up, code 402	Add credit or choose a plan in the console, then reconnect.
Daily audio limit of the key, code 429	It resets at midnight Pacific time.
`billing is unavailable; retry shortly`, code 503	Reconnect after a short wait.
`session longer than 2 hours`	Open a new stream; long calls can be split across sessions.

If the connection drops without an error or done, finals you already received are complete; the utterance in progress is lost. Reconnect, send the configuration again and continue with the live audio. Treat a stream as complete only once done has arrived.

Limits

Limit	Value
File size	600 MB
File length	4 hours; 2 hours on self-serve accounts
Shortest file	0.05 s
Context prompt	500 characters; longer text is cut
Stream configuration	within 10 s of connecting
Stream audio message	64 KB
Unprocessed stream audio	5 s
Stream session	2 hours
Parallel file requests per key (self-serve)	8
Parallel streams per key (self-serve)	4
Audio per key per day (self-serve)	20 hours, reset at midnight Pacific time
Active keys per account	10

Audio formats

Files: WAV, FLAC, MP3, OGG, M4A, MP4, WebM and other common audio or video containers. Any sample rate; stereo is mixed to mono, and audio is resampled to 16 kHz on our side.

Streams: raw 16-bit little-endian PCM, mono, at 8000, 16000, 24000 or 48000 Hz. No headers or containers: send the samples only. If your telephony platform gives you μ-law, convert it to 16-bit PCM first.