> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors, limits and retry safety

> Handle uncertain responses without duplicating mutations.

Errors use a structured envelope:

```json theme={null}
{"error":{"code":"insufficient_scope","message":"Requires calls:read","requestId":"00000000-0000-4000-8000-000000000003"}}
```

Validation errors may also contain `details:[{path,message}]`. Save the
`X-Request-Id` response header for support. Do not log tokens or sensitive payloads.

| Status | Action |
| - | - |
| 400 | Correct invalid request fields or headers. |
| 401 | Check credential expiry, revocation, environment and personal membership. |
| 403 | Check scopes and permitted ownership. |
| 404 | Check the resource ID and access; inaccessible resources are hidden. |
| 409 | Resolve idempotency or state conflicts; do not blindly repeat with a new key. |
| 410 | The v1 API has been retired on the responding deployment; use scoped v2 credentials. |
| 413 | Reduce the import size. |
| 422 | Correct the webhook challenge response. |
| 429 | Wait according to `Retry-After` before retrying. |
| 503 | Retry reads or receipt-backed writes with backoff and the same operation key. |

## Limits

Limits apply across API instances: 300 requests per key per minute and 1,200 per
workspace per minute. `RateLimit-Limit` and `RateLimit-Remaining` describe the key
bucket. The workspace may exhaust its limit first. HTTP 429 includes `Retry-After`
in seconds. Limits reset on clock-minute boundaries.

Contacts, lists, calls and change-feed pages return up to 200 rows. Delivery and
attempt history return the latest 100 entries. Imports accept up to 10,000 rows;
the serialized parsed request is limited to 10,000,000 JavaScript string units
(UTF-16 code units), and the HTTP request must also fit the server's JSON body limit.
Call timestamp ranges and analytics calendar ranges
are limited to 366 days. There are at most 100 webhook subscriptions per key.

## A legacy list cannot be deleted through the API

`409 legacy_upload_delete_requires_app` means the list has a legacy file upload
linked to it. The API refuses the deletion because it could also delete uploaded
contacts. No records are removed. Manage that list in the PowerDialer app, or use
[membership deletion](/api-reference/remove-membership) to unlink a single contact
while preserving the contact record. Retrying with a new idempotency key will not
remove this restriction.

## Retry safety

All contact/list writes, membership changes, import creation, webhook PUT/PATCH
and delivery replay require `Idempotency-Key`: 1–200 letters, digits, `.`, `_`, `:`
or `-`. Persist a UUID with the logical operation before the first request.

A matching retry returns the original response **status and body**, with
`Idempotency-Replayed: true`. A changed request under the same key returns 409.
Current permissions and endpoint preconditions still apply. For example, webhook
enable checks verification before returning a saved response, and delivery replay
checks that the receiver is active and verified. Rotating or pausing a receiver
between attempts can therefore produce `409 verification_required` or
`409 inactive_webhook`. Restore the receiver deliberately; do not generate a new
operation key just to bypass a conflict.
Receipts survive resource deletion and belong to the credential; rotation keeps
them, but switching to a different credential does not reuse them. Object property
ordering does not matter; array ordering does.

A timeout does not mean the write failed. Retry with the same method, path, body
and persisted key after transient errors. Use exponential backoff with jitter and
an explicit request timeout. The replayed result is not current resource state;
fetch the resource if you need its current value.

**Exceptions:** webhook secret rotation and verification do not use idempotency
receipts. Never automatically retry them. Rotation immediately replaces a secret;
if its response is lost, explicitly rotate again, update the receiver, then verify.
Credential creation/rotation in Developers also exposes secrets once and must be
handled explicitly after an uncertain response.

No automatic receipt pruning is currently configured. Do not interpret that as an
unlimited-retention commitment; a supported retry horizon must accompany any
future retention policy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.