Request IDs

Every response carries an X-Request-Id header: a correlation id for that single request.

The request id is minted by the server. It is a uuidv7 generated when the request arrives, and it is the value returned in the X-Request-Id response header, embedded in every error envelope, and written to the platform's access log. It is never taken from the request.

If you send your own X-Request-Id, the platform does not echo it back and does not use it as the correlation id. It is recorded alongside the server's own id as clientRequestId on that request's log line (sanitized and truncated), so support can still line your trace up with ours. Quote the id the response gave you, not the one you sent.

curl -i https://your-app.example.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_PUBLICID.SECRET" \
  -H "X-Company-Id: 0190abcd-1234-7000-8000-000000000000"
# X-Request-Id: 0190abcd-1234-7000-8000-000000000000

Why the id is not yours to set

A client-settable correlation id is forgeable and non-unique: a caller could pin every request to one value, which would make the log useless for whoever is actually broken, or deliberately collide with another workspace's id. Minting it server side keeps every log line attributable to exactly one request.

On errors

The same id is embedded in every error envelope as requestId (see Errors):

{
  "error": {
    "code": "not_found",
    "message": "not found",
    "requestId": "0190abcd-1234-7000-8000-000000000000"
  }
}