Request Tracing

Two header pairs help trace requests through your application and across services:

Header	Direction	Purpose
`X-Request-ID`	request (optional) / response (always)	Unique identifier for a single request/response pair. The server generates a UUID v4 if you omit it.
`X-Correlation-ID`	request (optional) / response (always)	Identifier that flows across service boundaries for distributed tracing. The server generates a UUID v4 if you omit it.

Both IDs are auto-injected on every operation in the OpenAPI spec — you don't need to declare them per route.

Both IDs are also echoed in error bodies as request_id and correlation_id extensions (see Errors), so a single value identifies a failure across your logs, the API's logs, and any support ticket.

Request ID

Use X-Request-ID to tag one specific request. If you don't send one, the server generates a UUID v4 and returns it in the response.

GET https://api.benjipays.com/v2/whoami
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Request-ID: my-custom-request-id-12345

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: my-custom-request-id-12345

Typical uses:

Correlating logs across your application and the API.
Quoting a specific request when contacting support.
Tracking request flow through your application.

Correlation ID

Use X-Correlation-ID when a single logical operation hits multiple services and you want all of them to share one identifier.

Service A → Service B → Benji Pays API

# All three carry the same correlation ID
X-Correlation-ID: trace-abc-123

Example:

GET https://api.benjipays.com/v2/partners
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Correlation-ID: trace-abc-123

HTTP/1.1 200 OK
X-Correlation-ID: trace-abc-123

How they differ

Aspect	Request ID	Correlation ID
Scope	One request/response	One distributed operation
Lifetime	Per HTTP exchange	Spans many HTTP exchanges across services
Typical generator	Client or server	Originating service in your system

You can — and usually should — send both. They're independent.

In error responses

When the server returns an application/problem+json error, it includes both values in the body too:

{
  "type": "https://api.benjipays.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token",
  "instance": "/v2/whoami",
  "request_id": "5e3e7c8e-1a04-4f7e-9c1f-9e0c5b9b1a23",
  "correlation_id": "trace-abc-123"
}

This makes it easy to grep your logs for the same failure that support is looking at.

Best practices

Generate X-Correlation-ID at the edge of your system and propagate it on every outbound call.
Let the API generate X-Request-ID unless you have a specific reason to set one (e.g. correlating with a client-side log).
Capture both response headers into your application logs alongside the URL and status.