Errors and rate limits
Error shape
Section titled “Error shape”Most failures use a stable JSON code:
{ "ok": false, "error": "wrong_scope" }| Status | Code examples | Meaning |
|---|---|---|
402 | subscription_required, insufficient_credits | Messaging billing gate |
403 | forbidden, wrong_scope, no_bound_agent | Authentication or authorization failed |
404 | not_found, no_lead, unknown_route | Resource or route unavailable |
422 | bad_channel, bad_operation_id, bad_phone, invalid_phone, invalid_list | Invalid input |
429 | rate_limited | Fixed hourly request limit exceeded |
500 | db_connect_failed, insert_failed | Server-side failure |
Rate limits
Section titled “Rate limits”- API v1: 300 requests per key per fixed hour.
- Lead intake: 120 requests per key per fixed hour.
The current API returns 429 rate_limited without quota headers. Back off until the next hour boundary, add jitter, and avoid retry storms.
Retry guidance
Section titled “Retry guidance”Retry network failures, 429, and transient 5xx responses with exponential backoff. Do not automatically retry validation or authorization errors. Include a stable operation_id for message writes so a client retry cannot create duplicate work.