> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zouti.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Request-Id

> O identificador de cada requisição: onde ele vem e por que guardá-lo.

Toda resposta da API, de sucesso ou de erro, traz o header `Request-Id` com o identificador
único da requisição:

```text theme={null}
Request-Id: req_8f2kq1x7c3m9v4b6n0zd5a
```

* **Mesmo valor no corpo do erro.** Num erro, `error.request_id` é igual ao header `Request-Id`.
* **Gerado pela Zouti.** Um `Request-Id` enviado pelo cliente é ignorado: a resposta sempre traz
  um identificador novo.
* **Guarde no seu log.** Registre o `Request-Id` de cada chamada, ao menos das que falham. Com ele,
  o suporte encontra a requisição exata.
* **Informe ao suporte.** Ao relatar um problema, envie o `Request-Id`, o endpoint chamado e o
  horário aproximado.

Toda resposta da própria API traz `Request-Id`. As respostas geradas na borda (balanceador de
carga e WAF), antes de a requisição chegar à API, vêm sem corpo JSON e sem `Request-Id`:

* o `400` em texto puro de uma requisição em HTTP;
* o `429` do limite de volume por IP (veja [Limites de requisição](/concepts/rate-limits));
* o `403` da proteção do WAF contra entradas maliciosas conhecidas;
* um `5xx` do balanceador de carga, como `502`, `503` ou `504` quando a API não responde.

Nesses casos, registre o horário, o endpoint e o status para informar ao suporte.

<RequestExample>
  ```bash cURL theme={null}
  # -i mostra o header Request-Id; no erro, o mesmo valor vem em error.request_id.
  curl -i "https://api.zouti.com.br/v1/orders/ord_inexistente" \
    -H "Authorization: Bearer $ZOUTI_API_KEY"
  ```

  ```javascript Node.js theme={null}
  // Node.js 18+ (fetch nativo). Registra o Request-Id de cada chamada.
  const API_KEY = process.env.ZOUTI_API_KEY;
  const BASE_URL = 'https://api.zouti.com.br';

  async function zoutiGet(path) {
    const response = await fetch(`${BASE_URL}${path}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const requestId = response.headers.get('Request-Id');
    const body = await response.json();
    console.log(`GET ${path} → HTTP ${response.status} · Request-Id ${requestId}`);
    if (!response.ok) {
      // error.request_id é o mesmo valor do header.
      console.log(`${body.error.code}: ${body.error.message} (request_id ${body.error.request_id})`);
    }
    return body;
  }

  await zoutiGet('/v1/orders?limit=1');
  await zoutiGet('/v1/orders/ord_inexistente');
  ```

  ```python Python theme={null}
  # Python 3 com requests. Registra o Request-Id de cada chamada.
  import os

  import requests

  API_KEY = os.environ["ZOUTI_API_KEY"]
  BASE_URL = "https://api.zouti.com.br"


  def zouti_get(path):
      response = requests.get(
          f"{BASE_URL}{path}",
          headers={"Authorization": f"Bearer {API_KEY}"},
          timeout=30,
      )
      request_id = response.headers.get("Request-Id")
      body = response.json()
      print(f"GET {path} → HTTP {response.status_code} · Request-Id {request_id}")
      if not response.ok:
          # error.request_id é o mesmo valor do header.
          error = body["error"]
          print(f"{error['code']}: {error['message']} (request_id {error['request_id']})")
      return body


  zouti_get("/v1/orders?limit=1")
  zouti_get("/v1/orders/ord_inexistente")
  ```

  ```php PHP theme={null}
  <?php
  // PHP 7.4+ com a extensão curl. Registra o Request-Id de cada chamada.
  const BASE_URL = 'https://api.zouti.com.br';

  function zouti_get(string $path): array
  {
      $headers = [];
      $ch = curl_init(BASE_URL . $path);
      curl_setopt_array($ch, [
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ZOUTI_API_KEY')],
          CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
              $parts = explode(':', $line, 2);
              if (count($parts) === 2) {
                  $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
              }
              return strlen($line);
          },
      ]);
      $raw = curl_exec($ch);
      if ($raw === false) {
          throw new RuntimeException(curl_error($ch));
      }
      $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
      $body = json_decode($raw, true);
      printf("GET %s → HTTP %d · Request-Id %s\n", $path, $status, $headers['request-id'] ?? '-');
      if ($status !== 200) {
          // error.request_id é o mesmo valor do header.
          $error = $body['error'];
          printf("%s: %s (request_id %s)\n", $error['code'], $error['message'], $error['request_id']);
      }
      return $body;
  }

  zouti_get('/v1/orders?limit=1');
  zouti_get('/v1/orders/ord_inexistente');
  ```
</RequestExample>

<ResponseExample>
  ```json 404 theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "code": "resource_missing",
      "message": "Recurso não encontrado.",
      "request_id": "req_8f2kq1x7c3m9v4b6n0zd5a"
    }
  }
  ```

  ```text Headers theme={null}
  HTTP 404
  Request-Id: req_8f2kq1x7c3m9v4b6n0zd5a
  ```
</ResponseExample>


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