Errores, reintentos e idempotencia

Decidí cuándo corregir un request, repetirlo o reconciliar un write antes de intentar otra operación.

Formato de error

{
  "ok": false,
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable message"
  }
}

Usá error.code para decidir la acción y x-request-id para correlacionar el fallo con tus propios logs.

Elegí la acción según el tipo de error

Errores de auth, scope, tenant o validación → corregí el request o la credencial antes de repetir.
Mismo request que no puede resolver el problema → no lo repitas sin cambios.
Operación explícitamente segura para replay → repetí exactamente el mismo request.
Write con resultado ambiguo → reconciliá antes de generar otra acción.

Customer create

POST /api/customers no usa Idempotency-Key. Ante timeout, network failure o un 5xx ambiguo, buscá el mismo programId + email antes de volver a crear. Si aparece customer_email_conflict, resolvé también por search.

Purchase

Misma key + mismo payload → replay HTTP 200 con la misma transacción.
Misma key + payload diferente → 409 idempotency_conflict.
409 idempotency_in_progress → repetí sólo el mismo request con la misma key.
500 purchase_reconciliation_required → preservá request y key; verificá el estado antes de una nueva operación.

Rate limits

Ante 429 rate_limited, respetá los headers de rate limit que la respuesta efectivamente incluya. No dependas de una ventana o cantidad de reintentos fija si no viene expresada por la respuesta.

Reconciliar una compra

Conservá la Idempotency-Key, el payload original y transactionId cuando aparezca en los detalles del error. Leé GET /api/customers/{id}/state para observar el estado disponible antes de decidir la siguiente acción.