What does an error look like?
{
"error": {
"code": "insufficient_scope",
"message": "This key is read-only.",
"request_id": "req_6f1c2a9b3d4e5f60"
}
}code is stable and safe to branch on; message is for people; param names the field when one is at fault. Quote request_id (also in the X-Request-Id header) when you contact us.
| Status | Typical codes |
|---|---|
| 400 | invalid_cursor, invalid_phone |
| 401 / 403 | See Authentication |
| 404 | not_found, employee_not_found |
| 409 | call_not_cancellable, campaign_state, idempotency_request_in_progress |
| 422 | invalid_request, idempotency_key_reused, consent_required, webhook_url |
| 429 | rate_limited, daily_call_limit |
| 5xx | internal_error, service_unavailable: retry with the same Idempotency-Key |
What are the rate limits?
| Limit | Value |
|---|---|
| Reads | 120 requests a minute per key |
| Writes | 60 requests a minute per key |
| All requests of a workspace | 300 a minute |
| Calls placed through the API | 1,000 in 24 hours (100 before your first payment) |
| Contacts per campaign request | 1,000 |
| Request body | 1 MB |
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Over a limit you get 429 with Retry-After in seconds.
How do I retry safely?
Send an Idempotency-Key header on writes, using something unique to the action such as your lead or order id (up to 255 characters). For 24 hours, the same key with the same body returns the first answer with Idempotent-Replayed: true. The same key with a different body is 422 idempotency_key_reused; a repeat while the first is still running is 409 idempotency_request_in_progress.
How do dry runs work?
Every write accepts "dry_run": true. All checks run and the answer says what would happen, but nothing is written, nobody is called and nothing is charged. For POST /calls you get a call_preview listing each check (employee, number, coins, do-not-call, cooldown) and warnings such as a detail the employee does not use.
How does pagination work?
Lists return {"object": "list", "data": […], "has_more": true}, newest first. Pass limit (1 to 100, default 25) and starting_after set to the last id of the previous page.
Ready to try it? Sign in and open Developers to create a key, or ask us about your integration.