Errors

Every non-2xx response from Coinland Pay uses the same shape:

{
  "statusCode": 422,
  "errors": {
    "error": ["PAY_CURRENCY_NOT_ACCEPTED"]
  }
}

errors.error is an array of stable machine codes in UPPER_SNAKE. There is no human-readable message, in any language, anywhere in the response -- and that is deliberate: your customers read your copy, not ours. Map the code to a sentence you wrote, in the language your customer speaks.

Codes are append-only. A code that ships never changes meaning and is never renamed, because your translations and your alerting are keyed on it. New codes can appear, so branch on the ones you handle and fall through to a generic message for the rest.

Reading the envelope

const res = await fetch(url, init);
if (!res.ok) {
  const body = await res.json().catch(() => null);
  const code = body?.errors?.error?.[0] ?? "UNKNOWN";
  throw new CoinlandPayError(code, res.status);
}

Two details worth building around:

• The array can hold more than one code. Validation failures may report several at once. Take the first for your branch, log all of them.
• Do not branch on the status alone. Several codes share a status; the code is the contract and the status is transport detail.

Coinland Pay codes

Sessions and payments

An identical replay of POST /sessions is not an error: the same reference_id with the same payload returns the original session with a success status. Only a changed payload raises PAY_DUPLICATE_REFERENCE. See idempotency.

Payouts and refunds

These come from the payout direction and need a payout-class key.

INSUFFICIENT_BALANCE (422) and PAY_RATE_UNAVAILABLE (503) also reach this surface: the first when your business wallet does not cover amount + fee, the second when the coin has no live USD rate and the limits therefore cannot be enforced. A payout is refused rather than sent unmetered.

Customer identity binding

These come from payer identity binding: the mandatory customer block on every session, and the permanent link between your customer.id and the payer's Coinland account.

The payment confirm can also answer TOTP_REQUIRED, TOTP_NOT_ENROLLED or TOTP_INVALID -- the two-factor step-up every payment carries, at the same security tier as a withdrawal. Those are surfaced to the payer inside the widget and never reach your integration.

Your merchant account

The last five come from the business console rather than the merchant API. They are listed here because the console and the API share one envelope and one catalog, so a code you see in the browser means the same thing it would mean over the API.

Generic codes

These are platform-wide and can be returned by any endpoint.

Which errors to retry

Mapping codes to your own copy

Keep the map in one place, keyed on the code, with a fallback:

const MESSAGES = {
  PAY_SESSION_EXPIRED: "This checkout expired. Start again to get a fresh one.",
  PAY_CURRENCY_NOT_ACCEPTED: "We cannot take that coin right now.",
  PAY_AMOUNT_INVALID: "Something is wrong with the order total.",
  MERCHANT_DISABLED: "Coinland payments are unavailable at the moment.",
  RATE_LIMITED: "Too many attempts. Try again in a minute.",
};

// A code you have never seen must still produce a sentence, because new codes
// ship without a version bump.
export const messageFor = (code) => MESSAGES[code] ?? "Payment could not be completed.";

Log the raw code next to your own request id, whatever you show the customer. When you contact Coinland support, the code plus the session or payment id is enough to find the exact event.