Skip to main content
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, Specter, Link, Commerce v1, and Commerce v2.

​
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.
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.
Always send a UUID. Hellgate passes your ID on to third parties such as the card networks (see 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.
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.
  • Specter → Link: When a composed 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 and Commerce v2.
  • Not part of the response body. The request ID is returned only in the response header, not in error payloads.