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

# Request IDs

> Trace every Chataigne API call end to end with the X-Request-Id header and error.request_id.

Every response from the Chataigne API includes a unique **request ID**. It identifies a single
request in our logs and is the fastest way to get help: include it whenever you contact support
and we can pull up exactly what happened.

## Where to find it

Each response carries an `X-Request-Id` response header. On error responses, the same value is
mirrored in the body as `error.request_id`, so you can capture it even when you only have the
parsed JSON.

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

  ```text Response theme={null}
  HTTP/1.1 200 OK
  Content-Type: application/json
  X-Request-Id: req_7d3f9a1c84b24e0e
  X-RateLimit-Limit: 1000
  X-RateLimit-Remaining: 999

  {
    "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">
  Present on **every** response (success and error). Opaque, prefixed with `req_`.
</ResponseField>

<ResponseField name="error.request_id" type="string">
  On error responses, the request ID is also included in the body so you can log it alongside the
  error `type`, `code`, and `message`.
</ResponseField>

When a request fails, the body mirrors the header value:

```json Error response theme={null}
{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No special closing found with id 'scl_9zq4nm10'.",
    "request_id": "req_5e1a0b7c93df42aa"
  }
}
```

<Note>
  The value in `error.request_id` is always identical to the `X-Request-Id` response header for that
  request. Capture either one — they refer to the same call.
</Note>

## Echoing your own request ID

If you generate your own correlation ID, send it in the `x-request-id` **request** header. Chataigne
echoes that value back in the `X-Request-Id` response header instead of generating a new one, so a
single ID flows through your logs and ours.

<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 Response theme={null}
  HTTP/1.1 200 OK
  X-Request-Id: req_my-trace-2f8c1d
  ```
</CodeGroup>

<ParamField header="x-request-id" type="string">
  Optional. A correlation ID of your choosing. When supplied, it is returned verbatim as the
  `X-Request-Id` response header. Keep it unique per request so it stays useful for tracing.
</ParamField>

## Capturing it in your client

Read the header on every response and log it next to your own request metadata. The example below
captures the request ID on both success and failure.

```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(),
      // Optional: echo your own correlation ID back in the response.
      "x-request-id": requestId,
    },
    body: JSON.stringify({
      starts_at: "2026-12-24T17:00:00Z",
      ends_at: "2026-12-26T08:00:00Z",
      reason: "Christmas",
    }),
  },
);

// Available on success and error responses alike.
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>
  Request IDs are opaque identifiers for diagnostics only — never parse them or rely on their format.
  They are safe to log and share with support; they are not secrets, but **never** include your
  `x-api-key` in tickets, screenshots, or logs.
</Warning>

## Using request IDs for support

<Card title="Contacting support" icon="life-ring" horizontal>
  Include the request ID with any report. It lets us locate the exact request — including timing,
  the surface (`/v1` or `/admin/v1`), the key used, and the error returned — without round trips for
  more detail.
</Card>

A good report contains:

* The **request ID** (`X-Request-Id` or `error.request_id`).
* The **HTTP status** and error `type` / `code` (see [Errors](/concepts/errors)).
* The approximate **timestamp** of the request.

With those three values we can reproduce and resolve most issues in a single pass.