Errors

Every AptaPay error response has the same shape:

{
  "code": 422,
  "message": "The provider refused the payout.",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "The provider refused the payout.",
    "terminal": true,
    "retriable": false,
    "ambiguous": false,
    "details": { "...": "..." }
  }
}

error.code is a stable machine string. Build your logic against it and against the three booleans — never against the HTTP status alone, and never by string-matching message. Message text can change without notice; error.code will not.

The three booleans

Exactly one of the three is always true. This is the whole contract for safe retries.

terminal: true — a definitive outcome

The request reached a final answer. Retrying with the same idempotency key cannot change it.What to do: if it was a debit-adjacent operation, reverse your own side and surface the failure to your user. Do not retry.

retriable: true — nothing moved

Safe to retry. Nothing has been applied on our side or the provider’s.What to do: retry with backoff, using the same idempotency key. Never mint a new key for a retriable failure — a new key restarts the whole operation as if it were unrelated.

ambiguous: true — genuinely unknown

The outcome is unknown. The request may or may not have been applied by the provider.What to do: do not reverse anything. Poll GET /v1/collections/{reference} or GET /v1/payouts/{reference} until it resolves to a terminal status, or escalate to manual review after a reasonable timeout. Reversing an ambiguous outcome is exactly how a double-processing or a lost debit happens.

The single most damaging integration bug in a payments API is treating ambiguous as terminal and reversing. If you write only one branch carefully, write this one.

Handling the three cases

handle-error.ts

async function callWithRetry(fn: () => Promise<Response>, reference?: string) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fn();
    if (res.ok) return res.json();

    const { error } = await res.json();

    if (error.terminal) {
      // Final. Reverse our own side, tell the user, stop.
      throw new TerminalFailure(error.code, error.message);
    }

    if (error.retriable) {
      // Same idempotency key, exponential backoff.
      await sleep(2 ** attempt * 250);
      continue;
    }

    if (error.ambiguous) {
      // Do NOT reverse. Resolve by polling instead.
      return pollUntilTerminal(reference);
    }
  }
  throw new Error("retries exhausted");
}

Common codes

Class	Codes you will actually see
Terminal	`validation_failed`, `corridor_unsupported`, `amount_below_minimum`, `amount_above_maximum`, `payout_rejected_by_provider`, `charge_rejected_by_provider`, `bank_account_unresolvable`, `quote_expired`, `insufficient_tenant_float`
Ambiguous	`provider_unavailable`, `provider_timeout`, `provider_bad_response`, `internal_error`
Retriable	`request_in_progress`, `velocity_limit_exceeded`, `rate_limited`, `global_ceiling_reached`

A few worth calling out:

insufficient_tenant_float — your float balance in that currency does not cover the amount plus the estimated fee. Top up; the request itself was well-formed.
velocity_limit_exceeded — you crossed a per-hour, per-day or per-destination cap. Retriable, but retrying immediately will fail again; back off meaningfully.
idempotency_key_reused — the same key with different parameters. This is a bug or an attack on your side, never a legitimate retry. See Idempotency.
mode_mismatch — your body claimed a mode that disagrees with the key you signed with. Mode comes from the key. See Modes.

Status codes

Status	Meaning
`400`	Malformed request, or `mode_mismatch`.
`401`	Any signing failure. Deliberately carries no detail — see 401 triage.
`404`	Unknown reference.
`422`	Well-formed but rejected: validation, limits, float, idempotency conflict.
`429`	Rate limited.
`501`	Not implemented for your routed provider — for example refunds. Check Capabilities at integration time rather than discovering this in production.
`503`	Provider unavailable. Usually ambiguous — check the flags.

Getting started

Core concepts

Integration

The three booleans

Handling the three cases

Common codes

Status codes

​The three booleans

​Handling the three cases

​Common codes

​Status codes

The three booleans

Handling the three cases

Common codes

Status codes