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

# Request IDs

> Correlate requests, ensure idempotency, and simplify support

## Overview

We use two kinds of request identifiers:

* **Client Request ID (`client_request_id`)** — a UUID you generate and send on write operations to make them **idempotent** and easy to **correlate** across your systems.
* **Server Request ID (`request_id`)** — a string we generate to trace a specific API attempt. It’s always present in **error** responses (inside the `error.request_id` field) and may appear in headers when available.

***

## Client Request ID

Send a unique `client_request_id` with each **create/mutate** call. If you retry the *same* operation, **reuse the same `client_request_id`** so we don’t create duplicates.

### Endpoints that accept `client_request_id`

* `PATCH /api/v2/liquidity/onboarding/credit-limit` (`CreditLimitUpdateRequest`)
* `POST /api/v2/liquidity/onboarding/whitelist` (`AddWalletRequest`)
* `POST /api/v2/liquidity/utilization/drawdowns` (`CreateDrawdownRequest`)
* `PATCH /api/v2/liquidity/utilization/{id}/settlements` (`ConfirmSettlementRequest`)
* `POST /api/v2/liquidity/utilization/{id}/proofs` (`SubmitProofFormData`)

> We may extend `client_request_id` to other write endpoints over time.

### Idempotency semantics

* If a request with the same `client_request_id` is **replayed** with **identical** parameters, we return the original result.
* If it’s **replayed with different parameters**, we return an **idempotency error** (e.g., HTTP `409 Conflict` with `error.type: "idempotency_error"`).
* Idempotency keys are retained for a period; replays **outside the retention window** may be treated as new requests.

### Example (idempotent retry)

```http theme={null}
PATCH /api/v2/liquidity/onboarding/credit-limit
authorization: Bearer <token>
x-api-key: <key>
Content-Type: application/json
```

```json theme={null}
{
  "client_id": "35afa53d-43ea-47e6-8695-f4f569389a63",
  "client_request_id": "be7faa23-a157-4c19-a008-e9800b352118",
  "requested_amount": 150000,
  "justification": "Expansion into new corridor"
}
```

If this exact body is sent again with the same `client_request_id`, you’ll receive the same outcome without creating duplicate operations.

***

## Server Request ID

When something goes wrong, responses include a server-generated `request_id` in the error envelope:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "The 'amount' field is required.",
    "param": "amount",
    "doc_url": "https://docs.mansa.io/errors/missing_required_field",
    "request_id": "req_123456789"
  }
}
```

Share `request_id` with support for faster troubleshooting.

***

## Best practices

* **Generate UUIDv4** for `client_request_id` (one per unique operation).
* **Persist and reuse on retry** (network timeouts, 5xx, or 429 with backoff).
* **Don’t recycle IDs** across different operations or payloads.
* **Log both IDs**: your `client_request_id` and our `request_id` (from errors) to correlate end-to-end.
* **Combine with `metadata`** when you need extra business context (`metadata.reconciliation_run`, `metadata.psp_tx_id`, etc.).