Encabezado Idempotency-Key

La API de Bird admite la deduplicación opcional de solicitudes mediante la cabecera Idempotency-Key. Esta página define el contrato HTTP; para la estrategia de reintentos, consulta Idempotencia.

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 la cabecera o envías un valor vacío, la solicitud se procesa con normalidad y sin deduplicación. En los endpoints que declaran esta cabecera, 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.

Una respuesta repetida es idéntica byte a byte a la original (mismo código de estado, mismo cuerpo), distinguida solo 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.

Las respuestas 5xx nunca se almacenan en caché. Reintenta con retroceso usando la misma clave y solicitud. E01033 IdempotencyUnavailable significa que este intento no se ejecutó; no describe el resultado de un intento anterior. Conserva la clave en cada reintento.

Una operación puede surtir efecto antes de que su respuesta se retenga. Si esa respuesta se pierde o el bloqueo en curso expira, un reintento puede ejecutar la operación de nuevo. Un tiempo de espera agotado u otra respuesta 5xx no demuestra que la operación no haya tenido efecto.

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) cuando una operación lógica abarca varias llamadas SDK. Para detectar una repetició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.