Skip to main content
Cada POST autenticado de la API actual acepta un encabezado Idempotency-Key. Cuando una solicitud con una clave se completa correctamente, su respuesta se almacena durante 24 horas. Reintentar con la misma clave reproduce la respuesta almacenada en lugar de ejecutar la solicitud de nuevo. Esto hace que sea seguro reintentar una solicitud que agotó el tiempo de espera o falló por tu lado sin arriesgarte a un cargo, una transferencia o un recurso duplicados. Cualquier cadena única de hasta 255 bytes sirve como clave; un UUID es una buena opción predeterminada. Genera una clave nueva para cada operación distinta y reutiliza exactamente esa clave solo para reintentar esa operación.
Las respuestas reproducidas son idénticas byte a byte a la original, incluido el código de estado, y llevan un encabezado Idempotent-Replayed: true para que puedas distinguir una reproducción de una ejecución nueva.
Las respuestas de error también se reproducen. Si la solicitud original falló con un 4xx, reintentar con la misma clave devuelve ese mismo error. Ese fallo fue el resultado real de la solicitud; envía una clave nueva con la solicitud corregida.
Algunos detalles que conviene saber:
  • “Misma solicitud” significa que el método, la ruta, la cadena de consulta, el cuerpo y Api-Version-Date coinciden exactamente con los originales. Cualquier diferencia se trata como una reutilización de la clave y se rechaza con un 400 cuyo error.code es idempotency_key_mismatch.
  • Las claves están limitadas al llamador autenticado. Dos claves de API o usuarios diferentes pueden usar el mismo valor de clave sin colisionar.
  • El encabezado se ignora en solicitudes no autenticadas y en métodos distintos de POST: las solicitudes GET, PATCH y DELETE se pueden reintentar con seguridad.
  • Mientras la primera solicitud con una clave sigue en ejecución, un reintento devuelve un 409 cuyo error.code es idempotency_request_in_progress. Si la primera solicitud falló con un resultado desconocido (por ejemplo, una caída del servidor a mitad de la solicitud), los reintentos siguen devolviendo ese 409 hasta que la clave caduca. La API nunca se arriesga a ejecutar una solicitud dos veces.