SapaganDocs sapagan.com

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#

StatusMeaning
400The request failed validation (invalid_request) or its content was refused (invalid_content, invalid_template).
401No key, or an invalid or revoked key (unauthorized), or an identity token that does not verify (invalid_user_token).
403The key is valid but cannot do this. See below.
404The key's context cannot see the resource. Existence never leaks.
409The state does not allow it.
413The body is over 5 MB (payload_too_large).
422idempotency_key_reused, or an unprocessable request.
429Rate limited. Honour Retry-After.
5xxA failure on our side, or a provider. Retry with backoff.

Codes by status#

403

CodeMeaning
credential_kind_not_allowedThis kind of key cannot use the route.
insufficient_role, owner_required, operator_required, reviewer_requiredA console session without the role.
store_blocked, store_campaignA store is blocked or cannot do this.
organisation_suspended, workspace_archivedThe tenant is switched off.
origin_not_allowedA browser call from an origin the workspace does not list.
user_token_required, user_token_mismatch, identifier_not_allowed, identity_aliasIdentity token rules, reported per item on /v1/batch.
template_forbiddenThe template is not allowed for this credential.

409

CodeMeaning
invalid_transitionThe campaign is not in a state that allows this.
send_refusedA kill switch or store state refuses the send. details.reasons says why.
stale_reviewThe content changed since the reviewer looked.
profile_deletedThe person is deleted.
suppressed_addressThe address is on the suppression list.
no_deviceThe person has nothing to receive the message.
idempotency_in_progressA request with this Idempotency-Key is still running.
topic_exists, name_taken, local_part_takenA name is already used.
limit_reached, quota_exhaustedA limit or quota is used up.

429 and 5xx

CodeMeaning
rate_limitedToo many requests.
recipient_rate_limitedMore than 60 transactional messages accepted for one person in a minute.
workspace_daily_capThe 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#

WhatLimit
Request body5 MB.
POST /v1/batch itemEach item is checked on its own. A bad item fails alone, at its index.
External id1 to 200 characters.
Identifiers per profile20.
Event name1 to 200 characters.
Device token4096 characters.
Transactional, accepted per person60 a minute.
Transactional, reaching a person10 a minute and 100 an hour.
Devices per transactional send5.
Identity token lifetimeAt most 1 hour (use 10 minutes).
Web origins50 per workspace.
Track v2 /batch1000 items.
Webhook body and time64 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.