Skip to main content

​
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/v1/liquidity/onboarding/credit-limit (CreditLimitUpdateRequest)
  • POST /api/v1/liquidity/onboarding/whitelist (AddWalletRequest)
  • POST /api/v1/liquidity/utilization/drawdowns (CreateDrawdownRequest)
  • PATCH /api/v1/liquidity/utilization/{id}/settlements (ConfirmSettlementRequest)
  • POST /api/v1/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)

PATCH /api/v1/liquidity/onboarding/credit-limit
authorization: Bearer <token>
x-api-key: <key>
Content-Type: application/json

{
  "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: 
{
  "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.).