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

# Request tracing

> Correlate Connect requests with x-request-id across services

Use **`x-request-id`** to trace a single partner request through Connect, internal-router, and vendor HTTP calls.

## Client behavior

1. **Optional:** Send a unique ID on every request:

   ```
   x-request-id: your-trace-id-123
   ```

2. Connect attaches `req.requestId` and returns it in **`meta.requestId`** on every response (success or error).

3. If you omit the header, Connect generates `req_<uuid>`.

<Callout type="info">
  Request IDs are for **correlation only** — not for security, deduplication, or idempotency. Use `X-Idempotency-Key` for write retries when MS7 ships.
</Callout>

## Propagation chain

| Hop                       | Header                                       |
| ------------------------- | -------------------------------------------- |
| Partner → Connect         | `x-request-id` (in) → `meta.requestId` (out) |
| Connect → internal-router | `x-request-id`                               |
| Connect → vendor APIs     | `X-Humanly-Request-Id`                       |

Grep the same ID in qualifi-connectors and qualifi-api logs to reconstruct a call chain.

## Structured logging (Connect)

Each `/connect/*` request emits one log on response finish:

```json theme={null}
{
  "requestId": "...",
  "organizationId": "...",
  "teamId": "...",
  "vendor": "stub",
  "route": "/connect/stub/health",
  "method": "GET",
  "statusCode": 200,
  "latencyMs": 42,
  "userAgent": "..."
}
```

Logs **never** include request bodies, API keys, or vendor secrets.

## Sentry

Non-local environments tag Connect errors with `requestId`, `organizationId`, `vendor`, `route`, and `errorCode`.

## Support workflow

When opening a ticket with Humanly support, include:

* `meta.requestId` from the API response
* Timestamp and route
* HTTP status and `error.code` (if applicable)

## Example

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -s "https://connect.humanly.io/connect/stub/health" \
      -H "x-api-key: $CUSTOMER_KEY" \
      -H "x-request-id: sprockets-incident-2026-06-17-001" | jq '.meta.requestId'
    ```
  </Tab>
</Tabs>

## Related

* [Error envelope](/platform/error-envelope)
* [Getting started](/connect/getting-started)