> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Request IDs and correlation

> Use X-Request-ID to correlate clients, API responses, retries, logs, and support investigations.

Send a UUID v4 or v7 in `X-Request-ID` on every request attempt.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
X-Request-ID: {{requestId}}
```

If supplied, the API returns the identifier unchanged. If omitted, JobHandy generates one and returns it in the response.

## Purpose

A request ID links:

* the client attempt
* the API response
* customer logs and metrics
* JobHandy diagnostics
* a support case

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Scheduler
    participant Client
    participant API as JobHandy API
    participant Logs

    Scheduler->>Client: Start logical operation
    Client->>Client: Generate UUID for attempt 1
    Client->>API: Request + X-Request-ID
    API-->>Client: Response + same X-Request-ID
    Client->>Logs: Store operation, status, error code, request ID
```

## Validation

The value must be a UUID v4 or v7. Invalid values fail with `INVALID_REQUEST_ID`.

## One attempt, one request ID

Generate a new request ID for every HTTP attempt. Link retries using an internal logical-operation ID in your own telemetry.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
logicalOperationId: order-69eb125feddfff1d13676751-approval
attempt 1 requestId: <generated UUID v4/v7>
attempt 2 requestId: <new generated UUID v4/v7>
```

## Not an idempotency key

`X-Request-ID` does not:

* deduplicate requests
* guarantee exactly-once execution
* make `POST` or state transitions safe to replay
* prove that a timed-out write was not applied

After an ambiguous write outcome, re-read the affected resource before deciding whether another write is required.

## Logging recommendation

Log:

* UTC timestamp
* method and path template
* tenant context
* HTTP status
* API error code
* request ID
* retry attempt number
* internal logical-operation ID

Do not log the API key or unnecessary personal payload data.