# How does the EnableCalls API report errors and limits?

One error shape, clear limits, and safe retries for automation tools that resend on a timeout.

## What does an error look like?

```json
{
  "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](https://enablecalls.com/developers/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.

## More EnableCalls API docs

- [Overview](https://enablecalls.com/developers.md): Place AI phone calls, run calling campaigns and get every conversation's outcome, summary and transcript from your CRM, website, n8n, Make or Zapier.
- [Authentication](https://enablecalls.com/developers/authentication.md): Create EnableCalls API keys on the Developers page, choose full or read-only access, and send them as a Bearer token. Keys are shown once and can be revoked at once.
- [Calls and retries](https://enablecalls.com/developers/calls.md): How EnableCalls API calls move from queued to completed: calling hours, do-not-call, coins, the 30-minute cooldown, automatic retries for unanswered calls and every status.
- [Webhooks and events](https://enablecalls.com/developers/webhooks.md): Receive call.completed, call.not_connected, lead and appointment events on your URL, verify the HMAC-SHA256 signature, and understand retries and the event log.
- [n8n, Make, Zapier](https://enablecalls.com/developers/no-code.md): Call new leads from n8n, Make, Zapier or Pabbly Connect with an HTTP request to the EnableCalls API, and receive call results with a webhook trigger.
- [API reference](https://enablecalls.com/developers/reference.md): Every EnableCalls API endpoint: calls, leads, campaigns, contacts, appointments, do-not-call, webhooks, events, employees and phone numbers, with parameters and fields.

Canonical page: https://enablecalls.com/developers/errors
