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

# Identifiants de requête

> Suivez chaque appel à l'API Chataigne de bout en bout grâce à l'en-tête X-Request-Id et à error.request_id.

Chaque réponse de l'API Chataigne contient un **identifiant de requête** unique. Il permet de retrouver une requête
précise dans nos journaux et constitue le moyen le plus rapide d'obtenir de l'aide : transmettez-le lorsque vous
contactez l'assistance afin que nous puissions déterminer exactement ce qui s'est passé.

## Où le trouver

Chaque réponse contient l'en-tête `X-Request-Id`. En cas d'erreur, la même valeur est également présente dans le
corps sous `error.request_id`. Vous pouvez donc la récupérer même si vous ne disposez que du JSON analysé.

<CodeGroup>
  ```bash curl theme={null}
  curl -i https://server.chataigne.ai/v1/locations/loc_3kp9x2mq \
    -H "x-api-key: ch_org_live_8Qf2..."
  ```

  ```text Réponse theme={null}
  HTTP/1.1 200 OK
  Content-Type: application/json
  X-Request-Id: req_7d3f9a1c84b24e0e
  X-RateLimit-Limit: 10000
  X-RateLimit-Remaining: 9999

  {
    "id": "loc_3kp9x2mq",
    "object": "location",
    "organization_id": "org_a1b2c3d4",
    "name": "Pizzeria Centrale",
    "currency": "CHF",
    "country": "CH",
    "timezone": "Europe/Zurich",
    "default_language": "fr",
    "created_at": "2026-01-12T09:30:00Z",
    "updated_at": "2026-05-20T14:05:11Z"
  }
  ```
</CodeGroup>

<ResponseField name="X-Request-Id" type="string">
  Présent dans **toutes** les réponses, qu'elles indiquent une réussite ou une erreur. Il est opaque et commence par `req_`.
</ResponseField>

<ResponseField name="error.request_id" type="string">
  En cas d'erreur, l'identifiant de requête figure aussi dans le corps afin que vous puissiez le journaliser avec les
  champs `type`, `code` et `message` de l'erreur.
</ResponseField>

Lorsqu'une requête échoue, le corps reprend la valeur de l'en-tête :

```json Réponse d'erreur theme={null}
{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No special closing found with id 'scl_9zq4nm10'.",
    "request_id": "req_5e1a0b7c93df42aa"
  }
}
```

<Note>
  Pour une requête donnée, la valeur de `error.request_id` est toujours identique à celle de l'en-tête de réponse
  `X-Request-Id`. Vous pouvez enregistrer l'une ou l'autre : elles désignent le même appel.
</Note>

## Renvoyer votre propre identifiant de requête

Si vous générez votre propre identifiant de corrélation, envoyez-le dans l'en-tête de **requête** `x-request-id`.
Chataigne renvoie alors cette valeur dans l'en-tête de réponse `X-Request-Id` au lieu d'en générer une nouvelle. Un
seul identifiant circule ainsi dans vos journaux et dans les nôtres.

<CodeGroup>
  ```bash curl theme={null}
  curl -i https://server.chataigne.ai/v1/organizations/org_a1b2c3d4 \
    -H "x-api-key: ch_org_live_8Qf2..." \
    -H "x-request-id: req_my-trace-2f8c1d"
  ```

  ```text Réponse theme={null}
  HTTP/1.1 200 OK
  X-Request-Id: req_my-trace-2f8c1d
  ```
</CodeGroup>

<ParamField header="x-request-id" type="string">
  Facultatif. Identifiant de corrélation de votre choix. Lorsqu'il est fourni, il est renvoyé à l'identique dans
  l'en-tête de réponse `X-Request-Id`. Utilisez une valeur unique pour chaque requête afin de faciliter le suivi.
</ParamField>

## Le récupérer dans votre client

Lisez l'en-tête de chaque réponse et journalisez-le avec les métadonnées de votre requête. L'exemple suivant récupère
l'identifiant de requête en cas de réussite comme en cas d'échec.

```js Node.js theme={null}
const requestId = `req_trace-${crypto.randomUUID()}`;

const res = await fetch(
  "https://server.chataigne.ai/v1/locations/loc_3kp9x2mq/special_closings",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CHATAIGNE_API_KEY,
      "content-type": "application/json",
      "idempotency-key": crypto.randomUUID(),
      // Facultatif : renvoie votre identifiant de corrélation dans la réponse.
      "x-request-id": requestId,
    },
    body: JSON.stringify({
      starts_at: "2026-12-24T17:00:00Z",
      ends_at: "2026-12-26T08:00:00Z",
      reason: "Christmas",
    }),
  },
);

// Disponible aussi bien en cas de réussite que d'erreur.
const echoedRequestId = res.headers.get("x-request-id");

if (!res.ok) {
  const { error } = await res.json();
  // error.request_id === echoedRequestId
  console.error(`Chataigne API error [${echoedRequestId}]:`, error.message);
  throw new Error(error.message);
}

const specialClosing = await res.json();
console.log(`Created ${specialClosing.id} [${echoedRequestId}]`);
```

<Warning>
  Les identifiants de requête sont des valeurs opaques réservées au diagnostic : ne les analysez jamais et ne vous
  fiez pas à leur format. Vous pouvez les journaliser et les communiquer à l'assistance en toute sécurité. Ce ne sont
  pas des secrets, mais n'incluez **jamais** votre `x-api-key` dans un ticket, une capture d'écran ou un journal.
</Warning>

## Utiliser les identifiants de requête avec l'assistance

<Card title="Contacter l'assistance" icon="life-ring" horizontal>
  Indiquez l'identifiant de requête dans chaque signalement. Il nous permet de retrouver l’appel API exact, son heure
  et le résultat renvoyé, sans échanges supplémentaires.
</Card>

Un signalement utile contient :

* L'**identifiant de requête** (`X-Request-Id` ou `error.request_id`).
* Le **statut HTTP** ainsi que le `type` et le `code` de l'erreur (voir [Erreurs](/fr/concepts/errors)).
* L'**heure approximative** de la requête.

Avec ces trois valeurs, nous pouvons reproduire et résoudre la plupart des problèmes en une seule intervention.