Errors and status codes

When an API request fails, the response carries a standard HTTP status code plus a machine-readable body that explains what went wrong. Use the status code to decide how to react (retry, fix, or stop) and the body to decide what to fix. Error bodies typically include an error code, a human-readable message, and — for validation failures — the specific fields at fault. (Confirm the exact field names in your account.)

Reference

Status	Meaning	Typical cause	Recommended action
200 / 201	Success	Request accepted or resource created	Continue; read the body for IDs.
400 Bad Request	Malformed request	Invalid JSON, missing required field, bad token value	Fix the request; do not retry unchanged.
401 Unauthorized	Not authenticated	Missing, expired, or revoked API key/token	Refresh credentials, then retry.
403 Forbidden	Not permitted	Key lacks scope for this endpoint or resource	Adjust key permissions; do not retry unchanged.
404 Not Found	No such resource	Wrong ID, deleted Edition, or wrong path	Verify the identifier; do not retry unchanged.
409 Conflict	State conflict	Duplicate send, already-processed request	Reconcile state; safe to skip retry.
422 Unprocessable	Validation failed	Field-level errors (e.g. invalid subscriber address)	Read the errors list; fix and resend.
429 Too Many Requests	Rate limited	Sending requests faster than your quota	Back off and retry per Retry-After.
5xx Server Error	Transient failure	Temporary service issue	Retry with exponential backoff.

Example error body (shape is representative; confirm exact keys in your account):

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "fields": { "recipient": "not a valid subscriber address" }
  }
}

Notes

• Retry only when it can succeed. 429 and 5xx are retryable; use exponential backoff with jitter and honor the Retry-After header when present. 4xx errors (except 429) indicate a client-side problem — retrying the same request will fail again.
• Make writes idempotent. For send and create operations, pass a unique idempotency key (confirm the exact header in your account) so a retried request does not produce a duplicate Broadcast.
• Read the code, not the message. Match on the machine-readable code; the human-readable message text may change over time.
• Log the request ID. Responses generally include a correlation/request identifier — capture it so support can trace a specific failure.

Related

• Send a transactional email
• Personalization tags
• Metrics dictionary

---

Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.