Guide

Errors

Every error has an HTTP status, a stable code and a message you can show.

The error object

Errors use standard HTTP statuses. The body always has the same shape. code is stable and safe to branch on; message is written for people.

json

{
  "error": {
    "code": "invalid_request",
    "message": "Some fields are missing or invalid.",
    "details": [ { "path": "recipients.0.email", "message": "Invalid email address" } ]
  }
}

Send Accept-Language: fr to get messages in French. Codes never change with the language.

Retrying

4xx errors mean the request needs changing. Retrying the same request gives the same answer, except 409 request_in_progress and 429.
429 means slow down: wait for the Retry-After header.
500 and 503 are safe to retry with backoff. Reuse the same Idempotency-Key so nothing happens twice.

The full list is on the Error codes page.