IdempotencyReference

POST /v1/mail/send takes an Idempotency-Key header, up to 200 characters, scoped to your account. A repeat with the same key returns the first result with idempotent_replay: true, sends nothing and charges nothing.

{
  "id": "msg_63bd80dded23e6452659ed84",
  "object": "mail.message",
  "status": "sent",
  "recipients": 1,
  "idempotent_replay": true,
  "kaer": { "request_id": "req_…", "cost_usd": 0.0015 }
}

Retry other endpoints safely

Every other endpoint ignores Idempotency-Key. Search, images, maps and /v1/me only read, so a retry is safe but billed again. A retried chat completion runs again and is billed again.

• Retry 429 after Retry-After, and 502 or 503 with backoff: those calls were not charged.
• After 504 upstream_timeout, or 502 upstream_error from the edge, the first call may have run. Check your usage before you retry.