# 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

- `X-Request-ID` (request header): 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.
- `trace_id` (response body field): Generated by Arche and returned in the error envelope. Always present on a
  failed request, whether or not you sent a request ID.
- `X-Trace-Id` (response header): 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**

```bash
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"
```

```ts
const requestId = crypto.randomUUID()

const resolved = await fetch(
  'https://api.arche.fi/v1/edgar/companies:resolve?ticker=MSFT',
  {
    headers: {
      'X-Api-Key': apiKey!,
      'X-Request-ID': requestId,
      Accept: 'application/json',
    },
  },
)
```

```python
import uuid

request_id = str(uuid.uuid4())

resolved = requests.get(
    "https://api.arche.fi/v1/edgar/companies:resolve",
    params={"ticker": "MSFT"},
    headers={
        "X-Api-Key": api_key,
        "X-Request-ID": request_id,
        "Accept": "application/json",
    },
    timeout=30,
)
```

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](https://docs.arche.fi/errors):

```json
{
  "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
HTTP/2 401
x-trace-id: 00d8d6c6-8330-46d0-8799-68892f24fed9
x-request-id: your-value-here
```

Representative response:

```json
{ "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.

> **Tip:** 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](https://docs.arche.fi/reference): Browse the live OpenAPI contract rendered from the public schema.
- [Errors](https://docs.arche.fi/errors): Interpret machine-readable error responses and troubleshoot failed requests.
- [Rate limits](https://docs.arche.fi/rate-limits): Handle request budgets, backoff, and throughput-sensitive integrations.