Request IDs
Cada respuesta de la API incluye un header X-Request-ID que identifica esa petición
específica. Es el dato que convierte un “me falló ayer a la tarde” en algo que podemos
buscar.
Recibirlo
No hay que hacer nada: el header viene en toda respuesta, incluidas las de error 401,
403, 404, 422, 429 y 502.
Guarda este valor en tus logs junto con la respuesta. Si necesitas reportar un problema,
el X-Request-ID de la petición que falló es lo primero que vamos a pedirte — con él
encontramos la petición exacta en nuestros registros en segundos, sin adivinar.
La única excepción es el 500 InternalServerError. Una excepción no controlada se
responde desde una capa que está por fuera de donde se agrega el header, así que esa
respuesta no trae X-Request-ID — justo el caso en el que más falta hace. Del lado
nuestro el identificador sí queda registrado; para reportar un 500, pásanos la hora
exacta con zona horaria y el endpoint, y lo ubicamos igual.
Enviar el tuyo
Si tu sistema ya genera identificadores de petición, mándalos y los adoptamos: quedan en
nuestros logs y en el registro de auditoría, así que tu identificador y el nuestro son el
mismo y la traza cruza el límite entre ambos sistemas.
Debe ser un UUID versión 4 (con o sin guiones). Un valor con cualquier otro formato
se descarta en silencio y generamos uno nuestro en su lugar: la respuesta traerá un
X-Request-ID que no es el que enviaste, y tu identificador no quedará registrado en
ningún lado.
9f2c1a7b4e8d4c3fa1b6e5d0c7a92341); ambas formas son válidas.
Uno por intento, no por operación
Un request ID identifica un intento de petición. Si reintentas después de un timeout,
esa nueva petición lleva un request ID nuevo — así los dos intentos quedan
distinguibles en los registros.
Eso es exactamente lo contrario de una clave de idempotencia, que debe ser la misma
en todos los reintentos para que la operación no se ejecute dos veces. No uses el mismo
valor para ambas cosas:
Usar un identificador nuevo por intento como clave de idempotencia rompe la protección
contra duplicados sin dar ningún error: cada reintento se ve como una operación distinta.
En un endpoint que envía mensajes, eso significa que tu cliente recibe el mensaje dos
veces.
