> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ya.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Request IDs

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

# 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`.

```bash theme={null}
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
```

<Note>
  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.
</Note>

<Warning>
  **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.
</Warning>

## 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.

```bash theme={null}
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"
```

<Warning>
  **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.
</Warning>

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](/outbound/cart-abandonment)) |
| **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 |

<Warning>
  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.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.