Error Handling

All errors return a structured JSON body with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "invalid_recipient",
    "message": "The recipient email address is not valid.",
    "details": {
      "field": "to",
      "value": "not-an-email"
    }
  }
}

The details field is present on validation errors and provides field-level context.

HTTP status codes

Status	Meaning
`200`	Success
`201`	Resource created
`400`	Validation error — check the `error.details` field
`401`	Missing or invalid API key
`403`	API key does not have permission for this action
`404`	Resource not found
`409`	Conflict — resource already exists (e.g. duplicate email on upsert)
`422`	Unprocessable — the request was well-formed but failed business logic
`429`	Rate limited — back off and retry after `Retry-After` seconds
`500`	Internal server error — contact support if this persists

Error codes

Code	HTTP	Description
`unauthorized`	401	API key is missing or invalid
`forbidden`	403	Key lacks permission for this resource
`not_found`	404	The requested resource does not exist
`validation_error`	400	One or more fields failed validation
`invalid_recipient`	400	The `to` address is not a valid email
`domain_not_verified`	422	Sending domain is not yet verified
`domain_limit_reached`	422	Free plan allows one sending domain
`rate_limited`	429	Rate limit exceeded; see `Retry-After`
`contact_not_found`	404	No contact with that ID exists
`campaign_not_draft`	422	Campaign cannot be modified after sending
`duplicate_email`	409	A contact with that email already exists
`internal_error`	500	Unexpected server error

Retries

Retry on 500 and 429 errors using exponential backoff. Do not retry 400, 401, 403, or 404 — these indicate a client-side problem that will not resolve on its own.

HTTP status codes

Error codes

Retries

On this page