Request IDs

Identifica cada petición para que un problema se pueda rastrear de punta a punta.

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.

curl -i https://api.ya.onl/v1/orders -H "X-API-Key: yv_live_v1_tu_api_key"

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: 9f2c1a7b4e8d4c3fa1b6e5d0c7a92341

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.

curl https://api.ya.onl/v1/orders \
  -H "X-API-Key: yv_live_v1_tu_api_key" \
  -H "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000"

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.

Los identificadores que generamos nosotros son 32 caracteres hexadecimales sin guiones (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:

	Request ID	Clave de idempotencia
Header o campo	`X-Request-ID`	depende del endpoint (por ejemplo `event_id` en Mensajes de Plantilla)
Cambia entre reintentos	Sí, uno por intento	No, debe repetirse
Para qué sirve	Rastrear qué pasó	Evitar que la operación ocurra dos veces
Quién lo elige	Tú o nosotros	Siempre tú, desde tu dominio

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.