# Request Tracing

Use X-Request-ID and X-Correlation-ID to trace individual requests and distributed flows.

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](./errors.md)), 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.

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

```http
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.

```text
Service A → Service B → Benji Pays API

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

Example:

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

```http
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:

```json
{
  "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.