Request IDs

When a request fails, the fastest path to an answer is a single identifier that appears in your logs, in the API response, and in our systems. Arche uses two identifiers for this, and they do different jobs.

Two identifiers

Name
X-Request-ID
Type
request header
Description
Supplied by you. Arche echoes it back and records it, so the value you chose is searchable on both sides. Optional, but strongly recommended for anything running unattended.
Name
trace_id
Type
response body field
Description
Generated by Arche and returned in the error envelope. Always present on a failed request, whether or not you sent a request ID.
Name
X-Trace-Id
Type
response header
Description
The same Arche identifier, on every response including successful ones. Capture it when a call returns 200 but the answer looks wrong — there is no error envelope to read trace_id from in that case.

Use X-Request-ID when you want your own identifier to survive the round trip — a job ID, a task ID, a correlation ID from your queue. Use trace_id when you did not send one and still need something to quote.

Sending a request ID

Set the header on every call. Any value that is unique to the request works; a UUID is a good default.

Send a request ID

curl -X GET "https://api.arche.fi/v1/edgar/companies:resolve?ticker=MSFT" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Log the value you sent alongside the response status. That one line is usually enough to resolve a support thread without a reproduction.

Reading the trace ID

Every error response carries trace_id inside the error envelope described in Errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "http_status": 400,
    "message": "from must be <= to",
    "details": {},
    "trace_id": "req-123"
  }
}

trace_id is present even when the request succeeded from your client's point of view but failed downstream, so prefer it over inferring identity from timestamps.

The header carries the same value as the body field:

HTTP/2 401
x-trace-id: 00d8d6c6-8330-46d0-8799-68892f24fed9
x-request-id: your-value-here

Representative response:

{ "error": { "trace_id": "00d8d6c6-8330-46d0-8799-68892f24fed9" } }

Logging X-Trace-Id on every response, not only on failures, is what makes a "the numbers look wrong" report answerable. Those requests return 200 and carry no error body.

Capture both values. X-Request-ID ties the failure to your workload; trace_id ties it to ours. Together they remove almost all guesswork.

Escalating an issue

Include the following when you contact support:

the X-Request-ID you sent, if any
the trace_id from the error envelope, or X-Trace-Id if the call succeeded
the request path and query parameters
the HTTP status and the code from the error envelope
the approximate time of the request, with timezone

The developer portal surfaces the request identifier on failed interactions, so you can copy it directly from the error notice rather than reconstructing it from logs.

Next steps

API reference

Browse the live OpenAPI contract rendered from the public schema.

Errors

Interpret machine-readable error responses and troubleshoot failed requests.

Rate limits

Handle request budgets, backoff, and throughput-sensitive integrations.