The X-Request-ID Header

To ensure robust traceability, debugging, and idempotency across our systems, our API requires an X-Request-ID header on all incoming requests.

This header uniquely identifies each API request you make. If a request fails or you need support, providing this ID allows our engineering team to trace the exact lifecycle of your request through our microservices.

The Requirement

You must include the X-Request-ID in the HTTP headers of your request.
The value must be a valid UUID Version 4 (UUIDv4) string.

Example Header:

X-Request-ID: 123e4567-e89b-12d3-a456-426614174000

Response Header Echo

When you send a valid X-Request-ID in your request, the API will return this exact same ID back to you in the HTTP response headers.

Example Response Header:

X-Request-ID: 123e4567-e89b-12d3-a456-426614174000

This behavior allows you to easily match asynchronous requests to their corresponding responses within your own client applications, monitoring tools, and logs.

Error Handling

If the X-Request-ID header is missing, malformed, or not a valid UUIDv4, the API will reject the request with a 400 Bad Request HTTP status.

You will receive the following JSON error response:

{
  "code": "ERR_INVALID_REQUEST_ID",
  "message": "Invalid Request ID in the request header."
}

How to Generate a UUIDv4

Here are examples of how to generate a valid UUIDv4 in popular programming languages to include in your API requests.

Example Code

const { v4: uuidv4 } = require('uuid');
const axios = require('axios');
const requestId = uuidv4();

axios.post('https://api.yourdomain.com/v1/items', payload, {
  headers: {
    'X-Request-ID': requestId,
    'Content-Type': 'application/json'
  }
});

import uuidimport

requestsrequest_id = str(uuid.uuid4())
headers = {
  'X-Request-ID': request_id,
  'Content-Type': 'application/json'
}
response = requests.post('https://api.yourdomain.com/v1/items', json=payload, headers=headers)

import (
  "net/http"
  "github.com/google/uuid"
)

func buildRequest() *http.Request {
  req, _ := http.NewRequest("POST", "https://api.yourdomain.com/v1/items", body)           

  // Generate and set the UUIDv
  req.Header.Set("X-Request-ID", uuid.New().String())
  req.Header.Set("Content-Type", "application/json")
  return req
}

curl -X POST "https://api.yourdomain.com/v1/items" \
     -H "X-Request-ID: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Item"}'

Testing in API Clients

If you are exploring our API using desktop clients, you can automate this header so you don't have to type it manually:

Insomnia: In the headers tab, type X-Request-ID, then in the value field, type uuid, press Ctrl + Space (or Cmd + Space), and select the UUID tag.
Postman: In the headers tab, set the key to X-Request-ID and the value to exactly {{$guid}}. Postman will dynamically inject a v4 UUID when you hit Send.