Errors, idempotency and retries

The API error format, how the SDK handles retries and how to use idempotency to avoid duplicate sends.

API errors come in a consistent format, with type, code, message and (when applicable) field:

{
  "error": {
    "type": "invalid_request",
    "code": "validation_error",
    "message": "subject is required",
    "field": "subject",
    "request_id": "req_..."
  }
}

Retries

The SDK automatically retries transient errors (network, 429, 5xx) with exponential backoff. Validation errors (4xx) are not retried — fix the request.

Idempotency

To ensure a retry does not send the email twice, pass an idempotency key. Requests with the same key are processed exactly once:

await publiq.emails.send(
  { from, to, templateKey: 'welcome-email' },
  { idempotencyKey: 'signup-user-123' },
);