Error shape
Every error response is JSON with a stable code so your client can switch on it.
Shape
{ "error": "pro_required", "message": "This feature requires quik.md Pro" }Always inspect the error field, not the HTTP status alone. Status codes are stable but the human-readable message may change between releases.
Catalogue
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | Body or query failed validation. The message contains the zod issue. |
| 401 | unauthorized | Missing or invalid Bearer token / session. |
| 402 | pro_required | The endpoint or feature requires a Pro plan (organize:true, voice transcribe, webhooks). |
| 403 | forbidden | Authenticated, but the resource isn't yours. |
| 404 | not_found | Resource doesn't exist or has been archived. |
| 413 | audio_too_large | Audio upload exceeds 10 MB. Split or compress. |
| 429 | rate_limited | Per-user request rate hit. Response includes retry_after (seconds) + Retry-After header. Free: 60/min, 1000/day. Pro: 300/min, 10000/day. |
| 429 | ai_rate_limited | Per-user daily AI cap hit. Retry after midnight UTC. |
| 429 | trial_quota_exceeded | Trial daily entry cap hit. Wait until UTC midnight or upgrade. |
