Errors

Every Thiqwave error uses one JSON envelope. Provider raw payloads and stack traces are never returned.

Error shape

{
  "error": {
    "code": "TXN_0001",
    "message": "Transaction not found",
    "correlation_id": "req_01HN8KDI6C",
    "details": null
  }
}

Field	Meaning
code	Stable DOMAIN_NNNN code. Safe to switch on.
message	Safe for end users; never a stack trace or provider payload.
correlation_id	Echoes your X-Request-ID (auto-generated if absent). Quote in support tickets.
details	Field-level errors for VAL_0001; null otherwise.

HTTP status map

Status	Meaning
400	Validation / bad input
401	Missing/invalid auth (ATH_0001)
403	Authenticated but not allowed (ATH_0002, CMP_0001)
404	Not found or not visible to your key
409	Conflict — idempotency, duplicate, invalid state
422	Compliance decision pending (CMP_0002)
429	Rate limited (see Idempotency & Rate Limits)
500	Unexpected error (GEN_0001, LED_0001)

Domain code prefixes

TXN Transaction · QTE Quote · LED Ledger · CMP Compliance · PTN Partner · CNT Participant · BEN Beneficiary · PAY Payment · SET Settlement · FX FX/Liquidity · WAL Wallet · CHN Chain · WEB Webhook · REC Reconciliation · AUD Audit · IDM Idempotency · ATH Auth · VAL Validation · GEN General

Common codes

Code	HTTP	Meaning
VAL_0001	400	DTO validation failed (see details)
ATH_0001	401	Missing authentication
ATH_0002	403	Insufficient scope
TXN_0001	404	Transaction not found
TXN_0002	409	Transaction state conflict
QTE_0001	400	Quote expired
QTE_0002	409	Quote already accepted
CMP_0001	403	Compliance check failed
CMP_0002	422	Compliance decision pending
IDM_0001	409	Idempotency key reused with different payload
IDM_0002	400	Missing Idempotency-Key on a money-moving endpoint
LED_0001	500	Ledger posting failed
GEN_0001	500	Unexpected internal error

Validation example

{
  "error": {
    "code": "VAL_0001",
    "message": "DTO validation failed",
    "correlation_id": "req_01HXYZ",
    "details": { "source_amount_minor": ["must be a numeric string"] }
  }
}

Correlation

Send X-Request-ID on every call. Log it alongside the response correlation_id — without it, support cannot trace the request.