Erros, idempotência e retries

O formato de erro da API, como o SDK trata retries e como usar idempotência para não enviar duplicado.

Erros da API vêm num formato consistente, com type, code, message e (quando aplicável) field:

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

Retries

O SDK retenta automaticamente erros temporários (rede, 429, 5xx) com backoff exponencial. Erros de validação (4xx) não são retentados — corrija o pedido.

Idempotência

Para garantir que um retry não envie o e-mail duas vezes, passe uma chave de idempotência. Requisições com a mesma chave são processadas uma única vez:

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