Resources
Errors and limits
The error body, the codes you will meet, idempotency and the limits that apply.
Error body#
Every non-2xx answer from /v1 has this body:
{ "error": { "code": "not_found", "message": "customer not found", "details": null } }code is stable. message is for people and may change. details carries extra data, for example validation issues on 400. Every response has an x-request-id header. Quote it to support.
The compatibility routes (/api/v1, /api/v2) answer in Customer.io's shape instead. See Migrating from Customer.io.
Status codes#
| Status | Meaning |
|---|---|
400 | The request failed validation (invalid_request) or its content was refused (invalid_content, invalid_template). |
401 | No key, or an invalid or revoked key (unauthorized), or an identity token that does not verify (invalid_user_token). |
403 | The key is valid but cannot do this. See below. |
404 | The key's context cannot see the resource. Existence never leaks. |
409 | The state does not allow it. |
413 | The body is over 5 MB (payload_too_large). |
422 | idempotency_key_reused, or an unprocessable request. |
429 | Rate limited. Honour Retry-After. |
5xx | A failure on our side, or a provider. Retry with backoff. |
Codes by status#
403
| Code | Meaning |
|---|---|
credential_kind_not_allowed | This kind of key cannot use the route. |
insufficient_role, owner_required, operator_required, reviewer_required | A console session without the role. |
store_blocked, store_campaign | A store is blocked or cannot do this. |
organisation_suspended, workspace_archived | The tenant is switched off. |
origin_not_allowed | A browser call from an origin the workspace does not list. |
user_token_required, user_token_mismatch, identifier_not_allowed, identity_alias | Identity token rules, reported per item on /v1/batch. |
template_forbidden | The template is not allowed for this credential. |
409
| Code | Meaning |
|---|---|
invalid_transition | The campaign is not in a state that allows this. |
send_refused | A kill switch or store state refuses the send. details.reasons says why. |
stale_review | The content changed since the reviewer looked. |
profile_deleted | The person is deleted. |
suppressed_address | The address is on the suppression list. |
no_device | The person has nothing to receive the message. |
idempotency_in_progress | A request with this Idempotency-Key is still running. |
topic_exists, name_taken, local_part_taken | A name is already used. |
limit_reached, quota_exhausted | A limit or quota is used up. |
429 and 5xx
| Code | Meaning |
|---|---|
rate_limited | Too many requests. |
recipient_rate_limited | More than 60 transactional messages accepted for one person in a minute. |
workspace_daily_cap | The workspace's daily cap is reached. |
send_failed (502) | The provider failed. |
unavailable, vault_unavailable, push_unavailable, email_unavailable, media_unavailable (503) | A dependency is not ready. Retry later. |
internal (500) | Our fault. The message is never detailed. |
Idempotency#
Send an Idempotency-Key header (1 to 255 characters) on a POST that you may retry. The first answer is stored for 24 hours.
- Same key, same credential, method, path, query and body: the stored answer replays, with
Idempotent-Replayed. - Same key with anything different:
422 idempotency_key_reused. - Same key while the first request still runs:
409 idempotency_in_progress. - A server error releases the key, so a retry runs.
POST /v1/batch saves the key in the same transaction as its work, so a crash never leaves a half-done batch. POST /v1/send also keeps the key on the message, so even a retry after 24 hours does not send twice.
Limits#
| What | Limit |
|---|---|
| Request body | 5 MB. |
POST /v1/batch item | Each item is checked on its own. A bad item fails alone, at its index. |
| External id | 1 to 200 characters. |
| Identifiers per profile | 20. |
| Event name | 1 to 200 characters. |
| Device token | 4096 characters. |
| Transactional, accepted per person | 60 a minute. |
| Transactional, reaching a person | 10 a minute and 100 an hour. |
| Devices per transactional send | 5. |
| Identity token lifetime | At most 1 hour (use 10 minutes). |
| Web origins | 50 per workspace. |
Track v2 /batch | 1000 items. |
| Webhook body and time | 64 KiB, 10 seconds. |
Some routes also have rate limits that you only meet in bursts, for example push open reports, in-app events, reports and the scope token exchange. The SDKs back off on 429 and honour Retry-After.
Retrying#
Retry 429 and 5xx with exponential backoff and jitter, and always with an Idempotency-Key on writes. Do not retry 400, 401, 403, 404 or 422: the same request fails the same way.
A marketing send is never retried after an ambiguous provider failure. A duplicate push to a person is worse than a missed one.
Status#
A public status page is not published yet. Health checks are at /healthz and /readyz on the API host.