Idempotencia y reintentos
Emitir una factura no se puede deshacer: si la red se corta después de que Chaski la creó, y tu sistema reintenta, podrías emitir dos. Para evitarlo, manda el header Idempotency-Key al crear facturas y notas de crédito:
POST /v1/invoicesIdempotency-Key: pedido-1042Usa un valor que identifique la operación en tu sistema: el id del pedido, del cobro o de la venta.
Qué hace Chaski con la clave
Sección titulada «Qué hace Chaski con la clave»| Caso | Respuesta |
|---|---|
| Misma clave y mismo body | La misma respuesta de la primera vez, sin crear nada. |
| Misma clave mientras la primera petición sigue en curso | 409 idempotency_in_progress. Reintenta en unos segundos. |
| Misma clave con otro body | 422 idempotency_key_reused. Es un error en tu sistema. |
La primera petición falló (por ejemplo, un 400) |
La clave queda libre: corrige y reintenta con la misma. |
Las claves se recuerdan 24 horas.
Cuándo reintentar
Sección titulada «Cuándo reintentar»| Respuesta | ¿Reintentar? |
|---|---|
| Error de red o timeout | Sí, con la misma clave. |
429 rate_limited |
Sí, después de los segundos del header Retry-After. |
500, 502, 503, 504 |
Sí, con espera creciente (1 s, 2 s, 4 s…). |
400, 402, 403, 404, 409, 422 |
No: hay que corregir algo antes. |
El SDK de JavaScript hace todo esto solo: genera la clave si no la pasas y la reutiliza en cada reintento.