Error Codes

Three error models, one set of HTTP conventions

CrissCross APIs share HTTP-status semantics — a 401 always means an auth problem, a 422 always means a business-rule violation — but the error body shape is defined per service domain. There are three distinct error models:

• Authentication (/auth/oauth2/token) returns a single-field envelope, { error }, where error is a short prose description — not an OAuth 2.0 RFC error code.
• Exchange uses a structured envelope with a stable, machine-readable code enum (QUOTE_EXPIRED, INSUFFICIENT_BALANCE, …) and a details object.
• Collect (payments), Payouts, and related services use a flat envelope (message, error, statusCode) aligned with standard HTTP semantics. Branching is driven by the HTTP status, except where error carries a machine-readable code — several Collect rejections share a single status and are told apart only by that code. Provider-specific failure reasons are carried on the transaction’s state, not on the HTTP error envelope. One exception: the 409 DUPLICATE_REFERENCE response on session creation has its own body shape — see Envelope.

These are three deliberate, distinct approaches. If you integrate one service, read just its section.

Shared HTTP-status semantics

Every CrissCross API uses standard REST status codes. Regardless of which service you call, the status code tells you the category of failure.

Tracing failed requests

Every response produced by the API — success or failure, including 401, 422, 429, and 500 — carries an x-trace-id response header (e.g. trace-0197a3f1-2b4c-7d5e-8f90-1a2b3c4d5e6f). It is generated server-side and is never echoed from the request.

Quote it when contacting support: it lets us trace the request end-to-end. The header is absent only when the request never reached the API — for example a malformed-JSON 400 or 413 rejected by the body parser, or an edge 502/503.

Authentication

The Authentication API (POST /auth/oauth2/token) implements the OAuth 2.0 Client Credentials flow, but its errors are not RFC 6749 error codes. Every error is a single-field envelope with a short prose description. This shape is specific to the token endpoint — once you have a token, the service you call next uses its own error envelope (see below).

Envelope

{
  "error": "Invalid client credentials"
}

Reference

The error string is a sentence for humans, not a stable machine code — branch on the HTTP status.

One more shape to know about: once you are calling other endpoints, a missing, invalid, or expired access token is rejected by the gateway with 401 and {"message": "Unauthorized"} — different again from the envelopes on this page. Treat it as the cue to request a fresh token.

Exchange

The Exchange API returns a structured error envelope with a stable, machine-readable code, a human-readable message, and a details object whose shape varies per code.

Envelope

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "Quote qut_550e8400-e29b-41d4-a716-446655440000 expired at 2026-04-21T14:00:00Z",
    "details": {
      "quoteId": "qut_550e8400-e29b-41d4-a716-446655440000",
      "expiredAt": "2026-04-21T14:00:00Z"
    }
  }
}

code is part of the API contract. message and details may be refined over time.

Code reference

Codes are grouped by the situation that produces them.

Request validation

Authentication & authorization

Currency & rates

Quotes & orders

Balances & amounts

Beneficiaries & deposits

Creating a beneficiary with an unsupported payment type (for example swift for USD), or without the wireDetails a USD wire requires, returns INVALID_REQUEST (400).

Withdrawals

Idempotency

Recommended handling for Exchange

type ExchangeError = {
  error: { code: string; message: string; details?: Record<string, unknown> };
};
function handle(status: number, body: ExchangeError) {
  switch (body.error.code) {
    case "UNAUTHENTICATED":
      return refreshTokenAndRetry();
    case "INSUFFICIENT_BALANCE":
    case "AMOUNT_OUT_OF_RANGE":
    case "QUOTE_EXPIRED":
      return surfaceToUser(body.error);
    case "INVALID_REQUEST":
    case "IDEMPOTENCY_CONFLICT":
      return logAndFail(body.error);
    default:
      if (status >= 500) return retryWithBackoff();
      return logAndFail(body.error);
  }
}

Collect (payments) and Payouts

Collect (card, bank transfer, mobile money, Pay-by-Bank, Hosted Checkout, Direct API), Payouts, and the related surfaces (Verification, Reporting, Settlement, Payers, Rate Locks) share a single error envelope. This envelope is different from Exchange’s by design: it is a flat shape aligned with standard HTTP semantics, where programmatic branching is driven by the HTTP status. Provider-specific failure reasons — card declines, mobile-money rejections, bank-transfer reversals — are carried on the transaction’s state, not on the HTTP error envelope.

Envelope

{
  "message": "Phone number is required when pre-filled by merchant",
  "error": "Bad Request",
  "statusCode": 400
}

One Collect response departs from this envelope: POST /checkout/session rejects a reused merchantReference with 409 and the body { "code": "DUPLICATE_REFERENCE", "message": "…", "existingSessionId": "…" } — there are no error or statusCode fields. Branch on code, and use existingSessionId to recover the original session (see Payment Status & Recovery).

How to branch

Drive control flow off the HTTP response status, then off error where it carries a machine-readable code. message is for logs, support tickets, and user-facing messaging — never pattern-match it.

type PaymentsError = { message: string; error: string; statusCode: number };
// Several rejections share one HTTP status and are told apart only by `error`.
const MACHINE_CODES = new Set([
  "fx_not_enabled",
  "rate_lock_invalid",
  "rate_lock_not_found",
  "rate_lock_currency_mismatch",
]);
function handle(status: number, body: PaymentsError) {
  if (MACHINE_CODES.has(body.error)) return handleByCode(body.error);
  if (status === 401) return refreshTokenAndRetry();
  if (status === 429 || status >= 500) return retryWithBackoff();
  if (status === 409) return refetchAndDecide();   // e.g. session already has a transaction
  if (status === 404) return treatAsMissing();
  if (status >= 400 && status < 500) return surfaceToUser(body.message);
  return null;
}

Provider error details on the transaction

Generic HTTP failures (validation, auth, missing resource, conflict) are conveyed by HTTP status + a clear message in the envelope above. Payment-method-specific failures — card declines, mobile-money rejections, bank-transfer reversals — are different: they don’t surface as HTTP errors. The request that initiates a payment returns 201 Created with the transaction’s current status — usually PENDING, though a fast decline can come back synchronously as FAILED or ERRORED. Handle any status. Later updates arrive by polling GET /v1/payment/{transactionId} or via webhooks, and the provider’s response is attached to the transaction’s authState, with the provider’s own code and message included verbatim.

The error/failed state on a transaction carries these fields:

Example — a card payment declined for insufficient funds, as returned by GET /v1/payment/{transactionId} (or synchronously from POST /v1/payment when the decline is immediate):

{
  "transactionId": "txn_01HV9N4Y3W5K2J0F8E2D7C1B0A",
  "status": "FAILED",
  "authState": {
    "state": "failed",
    "transitionedAt": "2026-05-13T10:30:42Z",
    "message": "Insufficient balance for transaction",
    "code": "payinInsufficientFunds",
    "connectorFailureCode": "2007",
    "connectorFailureMessage": "Insufficient funds"
  }
}

This lets your integration do both:

• Branch on the normalised code (the AuthFailureCode / ErrorCode enum below) for consistent cross-provider handling.
• Surface or log the raw connectorFailureCode / connectorFailureMessage when you need the provider’s own vocabulary — for reconciliation, support tickets, or showing the cardholder a network-specific reason.

The same shape applies to:

• The synchronous response from the payment-initiation endpoint.
• The transaction resource retrieved via polling.
• Webhook payloads carrying transaction state updates.

Normalised code reference (Collect & Payouts)

The values below are the complete set of normalised codes returned in authState.code across every payment method and payout rail. They split into two enums:

• AuthFailureCode — the underlying provider, acquirer, or payer rejected the transaction. Set when authState.state is failed.
• ErrorCode — a system, configuration, validation, or compliance problem prevented the transaction from being processed. Set when authState.state is error.

Codes are camelCase on the wire. Codes prefixed payin are returned only on Collect (payments) transactions; codes prefixed payout are returned only on Payouts transactions; all others can appear on either.

AuthFailureCode — provider declines and rejections

3-D Secure failures (card only)

Generic declines

Insufficient funds

Invalid data, cards, and PINs

Limits exceeded

Timeouts and conflicts

Deprecated codes

These five remain in the enum for older transactions and rails, but new integrations should branch on the granular payin* / payoutRecipient* codes above instead:

ErrorCode — system, validation, and compliance errors

System and processing

Validation

Capability gating

Compliance screening

For guidance on which codes are most common per payment method, and the user-facing messaging appropriate for each, see the per-method guides:

• Card
• Bank Transfer
• Pay By Bank
• Mobile Money
• Refunds

Rules of thumb (any service)

• Never branch on message. Message strings are for humans and may change without notice.
• HTTP status is always part of the contract. For Exchange, you also have a stable error.code. For Collect and Payouts, the HTTP status is the primary signal on the request response, and the normalised authState.code is the contract on the transaction.
• Retry only 429 and 5xx, with exponential backoff. Retrying 4xx blindly will fail again the same way.
• Guard retries against duplicates. Use Idempotency-Key on the endpoints that support it (see Conventions). On Collect, reuse the same merchantReference per order and reconcile via Search Payments; on Payouts, retry with the same merchantReference — a 409 DUPLICATE_REFERENCE confirms the original was accepted.
• Log the full error body on every failure, even codes you don’t recognise — it’s the fastest path to a support resolution.