Request IDs

Overview

The X-REQUEST-ID header is a unique identifier attached to each API request. It helps both clients and servers trace, debug, and correlate requests throughout distributed systems.

Why Use X-REQUEST-ID?

• Traceability: Track a request across multiple services and logs.
• Debugging: Quickly identify and troubleshoot issues by referencing the request ID.
• Idempotency: Prevent duplicate processing by reusing the same request ID for retries.

How to Use

1. Generate a Unique Request ID

• Use a version 4 UUID.
• Example: 4b5ef19e-4ad5-4750-8bf6-3e5238b976ec

2. Add the Header to Your API Request

Include the header in every request to the API, case-insensitive:

X-REQUEST-ID: 4b5ef19e-4ad5-4750-8bf6-3e5238b976ec

Example (cURL):

curl -X POST https://api.cert.zerohash.com/participants/customers/new \
  -H "X-REQUEST-ID: 4b5ef19e-4ad5-4750-8bf6-3e5238b976ec" \
  -H 'X-SCX-SIGNED: auto-generated on fly' \
  -H 'X-SCX-TIMESTAMP: auto-generated on fly' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{ ... }'

Example (JavaScript/Node.js):

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

axios.post('https://api.cert.zerohash.com/participants/customers/new', data, {
  headers: {
    'X-REQUEST-ID': uuidv4(),
    'X-SCX-SIGNED': 'auto-generated on fly',
  	'X-SCX-TIMESTAMP': 'auto-generated on fly'
  }
});

Best Practices

• Always send a new X-REQUEST-ID for each request.
• Log the request ID on the client side for troubleshooting.
• If retrying a request, reuse the same request ID.

Server Behavior

• The server will echo the X-REQUEST-ID in response header.
• If omitted, the server may generate one automatically.
• Use the request ID when contacting support for faster resolution.

Note: The X-REQUEST-ID header is for request tracking and is not used for authentication. Always include your authentication headers as required.