Errors

Every error has the same shape:

{ "error": { "type": "invalid_request", "message": "Validation failed" } }

type is stable and safe to branch on, and a type means the same thing, with the same status, on every endpoint. message is for people: it names the field or record at fault and often the call that fixes it, and its wording may change. Two extra fields can appear beside them, and no others:

• details, on most validation failures (422 invalid_request): the list of problems, each with the path of the failing field and a message.
• missing, on every 422 missing_variables: the names of the template variables that had no value. A failed entry in a batch carries it too.

POST /v1/automations/{id}/enroll is the one response that puts fields beside error rather than inside it; see Not an error. The conventions every endpoint shares are on the API overview.

Retrying safely

• Errors are never stored against an Idempotency-Key. Only responses below 400 are kept for replay, so after fixing a 4xx you can retry under the same key and the request runs again rather than replaying the error. A 5xx is not stored either, which means a retry under the same key also acts again: read what happened before retrying one.
• A key is reused only with the identical request. The same key with a different body answers 422 idempotency_key_reused and does nothing. That covers a changed body after a success, and a changed body while the first request is still running. Use a new key for a new request.
• 409 idempotency_in_progress means the same key is still being processed. A request that finds its key in use waits up to 8 seconds for the other to finish and returns that response; this answer means the other was still running after the wait. Nothing was done by the second request. Wait a moment and retry with the same key and body: if the first request succeeded you get its stored response, and if it failed your retry runs.
• A 207 is a success, and it is stored. A batch in which some entries failed replays whole under the same key. Resend only the failed entries, under a new key.

The Retry? column below means:

• Yes (after a pause): the condition clears by itself. Wait and send the same request again.
• No (fix the request): the same request fails the same way. Change it first.
• No (a person must act): nothing the caller can put in a request fixes it. Stop and tell someone.
• Sometimes: it depends on the case, as the row explains.

Error types

Not an error

These responses look like failures but are the API doing what was asked. None of them should be retried as they are.

• 202 with skipped: true from POST /v1/emails (or ok: true, skipped: true in a batch entry): every to address was dropped, so nothing was sent and the message is recorded with status: "rejected". reason says why: suppressed:<reason>, unsubscribed_from_topic:<topic>, or undeliverable_domain:<domain> for a recipient domain that cannot receive mail. When only some recipients are dropped the rest are sent to, and skipped is false. Every accepted send carries skipped, reason and approval_id, so check skipped for its value rather than for its presence.
• 202 with status: "pending_approval" and an approval_id: the key holds its sends for a person to release. See approvals.
• 200 with skipped: true from POST /v1/approvals/{id} with decision: "approve": every recipient unsubscribed or was suppressed while the draft waited. The approval is decided and the message is recorded as rejected.
• 207 from POST /v1/emails/batch when at least one entry failed, even if all did. Each entry in data has ok, and a failed one has its own error with type and message from the table above. failed counts them. A batch answers 202 only when every entry succeeded, and a body that is not an array of 1 to 100 messages, or that has an entry failing schema validation, fails whole with 422 invalid_request.
• Enrolling someone with POST /v1/automations/{id}/enroll: 200 with enrolled: false, a reason and enrollment: null means the person was not enrolled and that is the correct outcome. The reason is already_enrolled, previously_enrolled (the automation's reenrollment is never and the person has been through it), suppressed, unsubscribed_from_topic, exit_tag or required_tag_missing. When the automation itself cannot take anyone, the answer is 409 with enrolled: false, a reason of not_active, no_steps or topic_missing, enrollment: null, and an error object of type invalid_state whose message says what to fix. That one needs the automation changed, not a retry.
• 200 with automations_started: 0 from POST /v1/events: no automation waiting for that event enrolled the person, because none is active, or each one excluded them or already had them.
• 202 with ab_test.decided_by: "auto" from POST /v1/broadcasts/{id}/winner: the worker decided the test before this call could. The response is the campaign, and the ab_test.winner in it is the one that stands; a variant you passed was ignored.
• 200 with removed: false from DELETE /v1/suppressions/{email}: there was no suppression for that address in that scope.
• 200 instead of 201 from POST /v1/templates, POST /v1/topics and POST /v1/contact-properties: the record already existed and was updated.
• An Idempotent-Replay: true header: the response is the stored answer to an earlier request with the same key and body, and nothing was done this time.