Idempotencia
Envía un Idempotency-Key en las solicitudes POST para que un reintento después de un tiempo de espera agotado nunca cree lo mismo dos veces.
A veces la red falla cuando la solicitud ya se procesó. Para que los reintentos sean seguros, envía un encabezado Idempotency-Key en cualquier POST:
curl -X POST https://api.kuikcode.com/v1/codes \
-H "Authorization: Bearer kc_live_..." \
-H "Idempotency-Key: order-8812-code" \
-H "Content-Type: application/json" \
-d '{ "name": "Order 8812", "destination": { "type": "url", "url": "https://example.com/o/8812" } }'- La clave es cualquier cadena de hasta 255 caracteres que sea única por operación de tu lado: un id de pedido, un UUID, el id de una fila de base de datos.
- Una respuesta exitosa se guarda durante 24 horas por clave de API. Si repites la solicitud con la misma clave dentro de ese tiempo, recibes la respuesta guardada con el encabezado
Idempotent-Replayed: truey no se crea nada nuevo. - Solo se guardan las respuestas exitosas. Una solicitud fallida se puede reintentar con la misma clave.
- Las claves de idempotencia se limitan a la clave de API que las envió.
Qué puede recibir un reintento
| Situación | Respuesta |
|---|---|
| Misma clave, misma solicitud, la primera ya terminó | La respuesta guardada, con Idempotent-Replayed: true |
| Misma clave, misma solicitud, la primera sigue en curso | 409 idempotency_in_progress, reintenta en un momento |
| Misma clave, otro endpoint u otro payload | 422 idempotency_mismatch, usa una clave nueva |
| Misma clave, la primera falló | La solicitud se ejecuta de nuevo |
Las claves se registran en la base de datos con una regla de unicidad, así que dos solicitudes simultáneas nunca pueden crear una fila cada una: la primera reserva la clave y a la segunda se le informa que está en curso. Una solicitud que falla libera su clave de inmediato. Si la operación tuvo éxito pero su resultado no se pudo registrar, la clave queda reservada y los reintentos posteriores reciben un 409 que explica que el resultado es desconocido; lista el recurso para confirmar y luego continúa con una clave nueva. El resultado nunca es una escritura duplicada.
PATCH y DELETE se pueden repetir por naturaleza e ignoran el encabezado.
Límites de frecuencia
Los presupuestos son por clave y por minuto, con ventanas separadas para lecturas y escrituras.
Registro de cambios y versiones
La ruta lleva la versión mayor. Los cambios que solo agregan se publican sin aviso; los que rompen la compatibilidad reciben una versión nueva y un periodo de convivencia.