Encabezado Idempotency-Key

Usa Idempotency-Key para reintentar una solicitud sin crear una operación duplicada. La garantía es la aceptación exactamente una vez: dentro del plazo de retención de 3 horas, los reintentos con la misma clave y una solicitud idéntica deben resolverse en la operación original, aunque hayas perdido su respuesta. Para la estrategia de reintentos, consulta Idempotencia.

Encabezado de solicitud

Las mutaciones con ámbito de espacio de trabajo u organización admiten la reproducción de respuestas descrita a continuación. Las operaciones limitadas al usuario, las operaciones no autenticadas sin ámbito y los flujos no la utilizan. Las operaciones con un contrato de reproducción propio definen su comportamiento en su página de referencia.

Si omites el encabezado o envías un valor vacío, la solicitud se procesa con normalidad y sin deduplicación. En los endpoints que declaran este encabezado, una clave de más de 255 caracteres devuelve 422 con el código E01001 ValidationError.

Las claves tienen ámbito de espacio de trabajo, o de organización en los endpoints de nivel de organización, y se conservan durante unas 3 horas. Tras ese plazo, una solicitud que reutiliza la clave se procesa como una solicitud nueva.

Semántica de la respuesta

Una respuesta reproducida es idéntica byte a byte a la original (mismo código de estado, mismo cuerpo) y solo se distingue por el encabezado adicional:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" abarca el método, el endpoint, los parámetros de ruta y de consulta, y el cuerpo original de la solicitud. Una diferencia en estos valores, incluidos los espacios en blanco de JSON, provoca E01005. Las cargas multipart comparan los nombres de las partes, los nombres de archivo y el contenido; los límites y el orden de las partes no afectan a la reproducción. Ambos errores 409 se devuelven en la respuesta de error estándar.

Las respuestas conservadas pueden incluir rechazos 4xx. Usa una clave nueva al corregir una solicitud: si se conservó el rechazo, un reintento sin cambios lo reproduce y una solicitud modificada devuelve 409 E01005 IdempotencyKeyReuse.

Ante un tiempo de espera agotado o un 5xx, reintenta con un retroceso limitado usando la misma clave y una solicitud idéntica dentro de las tres horas. La garantía de aceptación exactamente una vez se aplica aunque se haya perdido la respuesta original. E01033 IdempotencyUnavailable significa que este intento no se ejecutó; no describe el resultado de un intento anterior. Conserva la clave en cada reintento.

En el envío de un mensaje, la aceptación exactamente una vez significa un único envío aceptado entre todos los reintentos coincidentes. Consulta el estado del mensaje para confirmar la entrega. Pasadas tres horas, comprueba el resultado de la operación original antes de volver a enviar: una clave caducada o una clave nueva pueden crear otra operación.

Comportamiento de SDK

Los SDK oficiales adjuntan un UUID Idempotency-Key autogenerado a cada solicitud de mutación, generado una vez por llamada lógica y reutilizado en todos los reintentos de esa llamada. Puedes proporcionar tu propia clave por llamada (idempotencyKey en TypeScript, option.WithIdempotencyKey en Go, idempotency_key en Python, new RequestOptions(idempotencyKey: ...) en PHP) cuando una operación lógica abarca varias llamadas de SDK. Para detectar una reproducción, lee el encabezado de respuesta Idempotency-Replay mediante el accesor de metadatos de transporte de cada SDK: .withResponse() en TypeScript, option.WithResponseInto en Go y with_raw_response en Python.

Relacionado

• Conceptos de idempotencia: estrategia de reintentos, diseño de claves y límites de reproducción
• Respuestas de error: la respuesta de error que contiene E01004 y E01005
• Mensajes de correo electrónico: el endpoint de envío, el lugar más común para usar una clave
• Conceptos de SDK: generación automática de claves y reintentos