Developers

Errors and limits

How a refusal looks, what each status means, when to try again, and how lists are paged.

Errors

An error has a detail. Most often it's a sentence that says what went wrong and what to do, written to be shown to your team:

Response · 422

{
  "detail": "Add the country code, e.g. +91 98765 43210. Without it the number could belong to more than one country, so it is never guessed."
}

Some are an object, with a code that won't change and a message:

Response · 403

{
  "detail": {
    "code": "api_key_scope_denied",
    "message": "This API key does not carry the 'contacts:write' scope.",
    "required_scopes": [
      "contacts:write"
    ]
  }
}

A body that doesn't fit the endpoint gets a list, one entry per field:

Response · 422 (shortened)

{
  "detail": [
    {
      "loc": [
        "body",
        "to_number"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Branch on the status and, where there is one, the code. Don't match the sentences: their wording gets better over time.

Status codes

Status

200, 201: Done. 201 when something was created.
400: The request can't be done as sent. detail says why.
401: No key, or a wrong, revoked or expired one.
402: Your credits, plan or spending limit doesn't cover it. Top up or change the limit in Pixl.
403: The key's scopes, its workspace, or its owner's role doesn't allow it; or the person opted out.
404: Not found. Something in another workspace answers the same way, so the API never confirms it exists.
409: Not ready yet: a recording still processing, or a request with the same Idempotency-Key still running. Try again shortly.
410: It existed and was removed.
413: Too large: too many records, or too big a body.
422: Refused by a rule, or a field is missing or invalid. detail says which.
423: Sending or calling is switched off.
429: Too many requests. Wait for the Retry-After header's seconds.
5xx: A problem on our side, or sending switched off for now (503). Try again with a growing wait.

When to retry

Retry a 429 after Retry-After, and a 5xx or a timeout with a growing wait: 2, 4, then 8 seconds.
Don't resend a 4xx unchanged. Fix what detail says first.
Retry reads freely. Be careful with sends.

Make sends safe to repeat

Starting a call and sending a template to one person take an Idempotency-Key header: send the same key again after a timeout and you get the first answer, with nothing sent twice. A list send doesn't, so if that request timed out, check GET /campaigns/{campaign_id}/recipients before you retry.

Limits

Each API key: 600 requests a minute, or your plan's API limit when that is higher. No limit on a plan with unlimited API use.
Each workspace: Your plan's API limit a minute, shared by all of the workspace's keys.
Lead link: 120 requests a minute per link, 64 KB and 50 leads a request.
Opt-in import: 10,000 records a request.
Text fields: As each endpoint lists, like 2,000 characters for a call's opening_context.

Past a limit you get a 429 with a Retry-After header (seconds), and detail says which limit it was. Requests the Pixl app itself makes are never counted. Keep a steady pace rather than bursts.

Pagination

Lists come in pages, in one of three ways:

Paging

cursor: Calls. Pass next_cursor back as cursor until it's null. limit up to 200.
since and cursor: The messages list and contacts that changed. next_cursor is always set; has_more says whether another page is waiting. Keep the last cursor and ask again later.
skip, limit: Conversations (up to 500), contacts (up to 100), opt-outs (up to 200). total is the full count.
limit, offset: Who got a send (up to 2,000). total and status_counts cover the whole send.

For a full copy, keep asking until a page comes back shorter than limit; for calls, until next_cursor is null.

Changelog

Changes

27 Oct 2026: A template to one person, the messages list, contacts that changed, custom fields on contacts, conversation pages, a name, variables and your own reference on a call, Idempotency-Key on calls and one-person sends, a per-key rate limit, a test flag on call events, and the API reference file.
26 Oct 2026: Event webhooks: calls, messages, conversations, consent and new leads, signed with a timestamp. The lead and contact webhook moves to CRM sync.
26 Oct 2026: These docs: calls, WhatsApp, contacts and consent, the lead link, and lead and contact webhooks.
25 Oct 2026: A new key starts with chat:write only, and full access is its own choice. Keys made before keep what they had.

Building on Pixl?

Tell us what you're connecting, and we'll help you set it up.

Talk to us