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) follows the OAuth 2.0 standard (RFC 6749 §5.2): { error, error_description, error_uri } with a fixed set of error values.
• 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; provider-specific failure reasons are carried on the transaction’s state, not on the HTTP error 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.

Authentication

The Authentication API (POST /auth/oauth2/token) implements OAuth 2.0 Client Credentials and returns errors in the format defined by RFC 6749 §5.2. 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

1
{
2
  "error": "invalid_client",
3
  "error_description": "Client authentication failed.",
4
  "error_uri": "https://payos.money/docs/authentication"
5
}

Code reference

For the Client Credentials flow used here, you will most commonly see invalid_client (bad credentials) and invalid_request (missing or malformed body).

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

1
{
2
  "error": {
3
    "code": "QUOTE_EXPIRED",
4
    "message": "Quote qut_550e8400-e29b-41d4-a716-446655440000 expired at 2026-04-21T14:00:00Z",
5
    "details": {
6
      "quoteId": "qut_550e8400-e29b-41d4-a716-446655440000",
7
      "expiredAt": "2026-04-21T14:00:00Z"
8
    }
9
  }
10
}

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

Withdrawals

Idempotency

Recommended handling for Exchange

1
type ExchangeError = {
2
  error: { code: string; message: string; details?: Record<string, unknown> };
3
};
4
5
function handle(status: number, body: ExchangeError) {
6
  switch (body.error.code) {
7
    case "UNAUTHENTICATED":
8
      return refreshTokenAndRetry();
9
10
    case "INSUFFICIENT_BALANCE":
11
    case "AMOUNT_OUT_OF_RANGE":
12
    case "QUOTE_EXPIRED":
13
      return surfaceToUser(body.error);
14
15
    case "INVALID_REQUEST":
16
    case "IDEMPOTENCY_CONFLICT":
17
      return logAndFail(body.error);
18
19
    default:
20
      if (status >= 500) return retryWithBackoff();
21
      return logAndFail(body.error);
22
  }
23
}

Collect (payments) and Payouts

Collect (card, bank transfer, mobile money, Pay-by-Bank, Hosted Checkout, Secure Fields, Direct API), Payouts, and the related surfaces (Verification, Reporting, Settlement, Payment Rules, Payers) 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

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

How to branch

Drive control flow off the HTTP response status. The body fields provide context for logs, support tickets, and user-facing messaging — they are not intended for programmatic branching.

1
type PaymentsError = { message: string; error: string; statusCode: string };
2
3
function handle(status: number, body: PaymentsError) {
4
  if (status === 401) return refreshTokenAndRetry();
5
  if (status === 429 || status >= 500) return retryWithBackoff();
6
  if (status === 409) return refetchAndDecide();   // e.g. session already has a transaction
7
  if (status === 404) return treatAsMissing();
8
  if (status >= 400 && status < 500) return surfaceToUser(body.message);
9
  return null;
10
}

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 even when the underlying provider declines the transaction. The provider’s response is attached to the transaction’s state instead, 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, returned as HTTP 201 from POST /payment:

1
{
2
  "transactionId": "txn_01HV9N4Y3W5K2J0F8E2D7C1B0A",
3
  "status": "failed",
4
  "authState": {
5
    "state": "failed",
6
    "transitionedAt": "2026-05-13T10:30:42Z",
7
    "message": "Insufficient balance for transaction",
8
    "code": "PAYIN_INSUFFICIENT_FUNDS",
9
    "connectorFailureCode": "2007",
10
    "connectorFailureMessage": "Insufficient funds"
11
  }
12
}

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 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

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: MTN MoMo, Airtel, M-Pesa, Tanzania 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.
• Use Idempotency-Key on every mutating call. It turns a 5xx retry from “did this just happen twice?” into a safe, repeatable operation.
• Log the full error body on every failure, even codes you don’t recognise — it’s the fastest path to a support resolution.