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

# Request IDs

> Every Hellgate Cloud Platform API response carries an x-request-id header. Send your own ID to correlate your logs with Hellgate's and to speed up support.

Every Hellgate® Cloud Platform API identifies each request with a **request ID**, carried in the `x-request-id`
HTTP header. You can send your own ID or let Hellgate generate one. Either way, the response returns the ID that
was used, so you can log it and quote it when you contact Hellgate support.

The behavior is the same for [Guardian](https://developer.hellgate.io/products/guardian/overview.md), [Specter](https://developer.hellgate.io/products/specter/overview.md),
[Link](https://developer.hellgate.io/products/link/overview.md), [Commerce v1](https://developer.hellgate.io/products/commerce/v1/overview.md), and
[Commerce v2](https://developer.hellgate.io/products/commerce/v2/overview.md).

## How it works

**1. Send an ID (optional)**

Set the `x-request-id` header on your request to a UUID that you generate, for example one from your own
tracing or logging system.

```http theme={null}
x-request-id: 3f2b8c4e-9a1d-4e7b-8c6f-2d5a9e0b7c41
```

**2. Hellgate uses or generates the ID**

Hellgate uses the ID you send. If the header is missing, or the value is shorter than 20 or longer than 200
characters, Hellgate ignores it and generates a new ID instead.

**3. Read the ID from the response**

Every response, including error responses, returns the ID in the `x-request-id` header.

```http theme={null}
HTTP/1.1 401 Unauthorized
x-request-id: 3f2b8c4e-9a1d-4e7b-8c6f-2d5a9e0b7c41
```

> [!WARNING]
>
> Always send a UUID. Hellgate passes your ID on to third parties such as the card networks (see
> [Propagation across services](#propagation-across-services)), and they can reject IDs in other formats. When a
> third party rejects the ID, the request that depends on it fails.

Treat the request IDs that Hellgate generates as opaque strings. Their format differs between products and not
all of them are UUIDs, so don't parse them or validate them against a pattern.

## Log the request ID

Store the `x-request-id` of every response alongside your own logs, particularly for failed requests. When you
contact Hellgate support about a specific request, include its request ID. It lets support find the exact
request in Hellgate's logs without needing timestamps or payloads.

> [!TIP]
>
> Sending your own ID is the easiest way to correlate. Generate a UUID for each request, record it in your logs,
> and send it as `x-request-id`, so the same ID appears on both sides.

## Propagation across services

When one Hellgate service calls another while handling your request, the request ID travels with the call, so a
single ID covers the whole chain:

* **Commerce v2 → Guardian → card networks**: Commerce v2 forwards the request ID to Guardian, and Guardian
  forwards it unchanged on its own calls to the card networks and other connected services, for example when it
  manages [network tokens](https://developer.hellgate.io/platform/network-tokens.md).
* **Specter → Link**: When a [composed](https://developer.hellgate.io/platform/composition.md) Specter instance calls Link, each backend call
  carries the decision's request ID followed by a unique suffix. The shared prefix ties every call back to its
  decision.

## What a request ID is not

* **Not an idempotency key.** Sending the same `x-request-id` twice does not stop a request from being processed
  twice. Commerce provides idempotency through a separate header; see
  [Commerce v1](https://developer.hellgate.io/products/commerce/v1/api-reference/getting-started.md#idempotency) and
  [Commerce v2](https://developer.hellgate.io/products/commerce/v2/api-reference/getting-started.md#idempotency).
* **Not part of the response body.** The request ID is returned only in the response header, not in error
  payloads.


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