Request tracing - Humanly Developer Docs

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

Client behavior

Optional: Send a unique ID on every request:
x-request-id: your-trace-id-123
Connect attaches req.requestId and returns it in meta.requestId on every response (success or error).
If you omit the header, Connect generates req_<uuid>.

Request IDs are for correlation only — not for security, deduplication, or idempotency. Use X-Idempotency-Key for write retries when MS7 ships.

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:

{
  "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

cURL

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'

​Client behavior

​Propagation chain

​Structured logging (Connect)

​Sentry

​Support workflow

​Example

​Related

Client behavior

Propagation chain

Structured logging (Connect)

Sentry

Support workflow

Example

Related