Error shapes
PyAI returns two error shapes depending on which layer produced the error. Branch
on the stable code, never the human message.
Data plane (gateway), OpenAI-compatible
Auth, scope, rate-limit, and billing errors use the OpenAI envelope:
Control plane, RFC 7807 problem+json
Request-validation and resource errors (e.g. 400, 404, 409) use
application/problem+json. The stable code is the last path segment of
type:
Error code reference
Rate limits
Every key has a per-second rate limit (with burst) and a cap on concurrent
realtime sessions, set by your plan. Exceeding either returns 429 with a
Retry-After header (seconds to wait). Back off and retry; the official SDKs do
this automatically.
Idempotency
POST /v1/transcription/jobs accepts an Idempotency-Key header so a retried
request can’t create a duplicate job:
- Same key + same body → the original response is replayed (no new job).
- Same key + different body →
409 idempotency_conflict.
Send a fresh idempotency key (e.g. a UUID) per logical operation, and reuse it
when retrying that exact operation after a network blip.
limit (1-100, default
20) and the previous page’s next_cursor as cursor. next_cursor is null
on the last page.
