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

> Identifique cada requisição para que um problema possa ser rastreado de ponta a ponta.

# Request IDs

Cada resposta da API inclui um header `X-Request-ID` que identifica aquela requisição
específica. É o dado que transforma um "falhou ontem à tarde" em algo que conseguimos
procurar.

## Recebendo

Não é preciso fazer nada: o header vem em toda resposta, incluindo os erros `401`, `403`,
`404`, `422`, `429` e `502`.

```bash theme={null}
curl -i https://api.ya.onl/v1/orders -H "X-API-Key: yv_live_v1_sua_api_key"
```

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

<Note>
  Guarde esse valor nos seus logs junto com a resposta. Se precisar reportar um problema, o
  `X-Request-ID` da requisição que falhou é a primeira coisa que vamos pedir — com ele
  encontramos a requisição exata nos nossos registros em segundos, sem adivinhar.
</Note>

<Warning>
  **A única exceção é o `500 InternalServerError`.** Uma exceção não tratada é respondida por
  uma camada que fica fora de onde o header é adicionado, então essa resposta **não traz**
  `X-Request-ID` — justamente o caso em que ele mais faz falta. Do nosso lado o identificador
  fica registrado; para reportar um `500`, envie o horário exato com fuso e o endpoint, que
  conseguimos localizar mesmo assim.
</Warning>

## Enviando o seu

Se o seu sistema já gera identificadores de requisição, envie-os e nós os adotamos: eles
ficam nos nossos logs e no registro de auditoria, então o seu identificador e o nosso são o
mesmo e o rastro cruza a fronteira entre os dois sistemas.

```bash theme={null}
curl https://api.ya.onl/v1/orders \
  -H "X-API-Key: yv_live_v1_sua_api_key" \
  -H "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000"
```

<Warning>
  **Deve ser um UUID versão 4** (com ou sem hífens). Um valor em qualquer outro formato é
  **descartado silenciosamente** e geramos um nosso no lugar: a resposta trará um
  `X-Request-ID` que não é o que você enviou, e o seu identificador não ficará registrado em
  lugar nenhum.
</Warning>

Os identificadores que geramos têm 32 caracteres hexadecimais sem hífens
(`9f2c1a7b4e8d4c3fa1b6e5d0c7a92341`); ambas as formas são válidas.

## Um por tentativa, não por operação

Um request ID identifica **uma tentativa de requisição**. Se você tentar de novo após um
timeout, essa nova requisição leva um request ID **novo** — é isso que mantém as duas
tentativas distinguíveis nos registros.

Isso é exatamente o oposto de uma **chave de idempotência**, que deve ser **a mesma** em
todas as tentativas para que a operação não seja executada duas vezes. Não use o mesmo
valor para as duas coisas:

| | Request ID | Chave de idempotência |
| - | - | - |
| **Header ou campo** | `X-Request-ID` | depende do endpoint (por exemplo `event_id` em [Mensagens de Template](/pt/outbound/cart-abandonment)) |
| **Muda entre tentativas** | Sim, um por tentativa | **Não**, deve se repetir |
| **Para que serve** | Rastrear o que aconteceu | Impedir que a operação aconteça duas vezes |
| **Quem escolhe** | Você ou nós | Sempre você, a partir do seu domínio |

<Warning>
  Usar um identificador novo por tentativa como chave de idempotência quebra a proteção
  contra duplicados sem gerar nenhum erro: cada tentativa parece uma operação distinta. Em
  um endpoint que envia mensagens, isso significa que o seu cliente recebe a mensagem duas
  vezes.
</Warning>


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