Error Reference

Every non-2xx response from the SohoPay API carries the same JSON envelope and a stable machine-readable code. This page lists all codes, what causes them, and how to recover — branch your error handling on error.code, never on the message text.

Error envelope

{
  "error": {
    "code": "INSUFFICIENT_CREDIT",
    "message": "Agent agt_7d1e5b2f has 3.50 USDC available; order requires 5.00.",
    "request_id": "req_a1b2c3d4"
  }
}

code — stable identifier from the table below. New codes may be added; treat unknown codes on a 5xx as retryable and unknown codes on a 4xx as terminal.
message — human-readable detail. Log it, don’t parse it.
request_id — attach this to any support ticket so the team can trace the exact request.

Error codes

Code	HTTP status	Description	Suggested recovery
`INVALID_API_KEY`	401	Key is missing, malformed, revoked, or used against the wrong environment (`sk_test_` vs `sk_live_`).	Check the base URL matches the key prefix; generate or rotate keys per Authentication. See Troubleshooting.
`INVALID_AGENT`	400	The `agent_id` doesn’t exist or doesn’t belong to the referenced merchant relationship.	Verify the `agt_` ID and that the agent was created under the right account. See Troubleshooting.
`ORDER_EXPIRED`	400	Payment was submitted after the order’s 10-minute TTL.	Create a fresh order and submit payment within 10 minutes. Don’t retry the expired order.
`INSUFFICIENT_CREDIT`	402	The agent’s available credit (or daily limit headroom) can’t cover the order amount.	Raise the agent’s limits, wait for the daily window to reset, or add vault collateral to increase borrowing capacity. See Troubleshooting.
`AML_DECLINED`	402	The agent’s wallet failed Didit AML screening. Settlement is blocked.	Not retryable. Review the flag and appeal process in AML Screening.
`AGENT_NOT_ALLOWLISTED`	403	The merchant hasn’t approved this agent to pay them.	Add the agent to the merchant’s allowlist, then retry. See Troubleshooting.
`AGENT_REVOKED`	403	The agent has been revoked and can no longer transact.	Not retryable. Create a replacement agent if the revocation was intentional; contact support if not.
`WITHDRAWAL_GATED`	409	Vault withdrawal is blocked while credit backed by that vault is outstanding.	Reduce outstanding credit to zero (or below the collateral requirement), then retry the withdrawal. See Troubleshooting.
`OUTSTANDING_BALANCE`	409	The operation (e.g. closing an agent or account) requires the outstanding balance to be repaid first.	Settle the balance, then retry. See Troubleshooting.
`RATE_LIMITED`	429	Request rate or a per-agent Policy Service limit was exceeded. Response includes `Retry-After`.	Wait `Retry-After` seconds and retry. Tune limits per Rate Limits.
`INTERNAL`	500	Unexpected error on SohoPay’s side.	Retry with exponential backoff and the same `Idempotency-Key`. If it persists, email support with the `request_id`.

Both INSUFFICIENT_CREDIT and AML_DECLINED return 402 Payment Required — always branch on the code, not the status. One is recoverable by the operator; the other is a compliance decision.

Retry strategy

Not every error deserves a retry. Classify by code: Retryable — back off exponentially (e.g. 1s, 2s, 4s, 8s, capped), reusing the same Idempotency-Key on POSTs so a retry can never double-execute:

RATE_LIMITED — but honor the Retry-After header instead of your own schedule.
INTERNAL — and any other 5xx, plus network timeouts.

Retryable after you change something — the same request will fail forever; fix the condition first:

INSUFFICIENT_CREDIT — raise limits or add collateral.
AGENT_NOT_ALLOWLISTED — allowlist the agent.
WITHDRAWAL_GATED, OUTSTANDING_BALANCE — clear the outstanding credit.
ORDER_EXPIRED — create a new order (a new ord_ ID, so a new idempotency key too).

Never retry — terminal outcomes:

INVALID_API_KEY, INVALID_AGENT — configuration bugs; fix your setup.
AML_DECLINED, AGENT_REVOKED — compliance or lifecycle decisions; retrying just burns rate limit.

Retrying AML_DECLINED in a loop looks like evasion behavior and can escalate the flag on the wallet. Handle it as a terminal state and route it to a human — see AML Screening.

A minimal classification in TypeScript:

const RETRYABLE = new Set(["RATE_LIMITED", "INTERNAL"]);

async function withRetries<T>(fn: () => Promise<T>, maxAttempts = 4): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      const code = err?.error?.code;
      const retryable = RETRYABLE.has(code) || err?.status >= 500;
      if (!retryable || attempt >= maxAttempts) throw err;
      const waitMs = err?.retryAfter
        ? err.retryAfter * 1000
        : Math.min(1000 * 2 ** (attempt - 1), 8000);
      await new Promise((r) => setTimeout(r, waitMs));
    }
  }
}

Patterns for handling declines inside a live payment flow — including surfacing them to agents mid-conversation — are covered in the error handling guide.

Next steps

Error Handling Guide

Decline and retry patterns inside the payment flow.

Troubleshooting

Step-by-step fixes for the most common failures.

Webhook Events

Failure events like payment.failed and agent.aml_declined.

Overview

Endpoints

Error Reference

Error envelope

Error codes

Retry strategy

Next steps

Error Handling Guide

Troubleshooting

Webhook Events

​Error envelope

​Error codes

​Retry strategy

​Next steps

Error Handling Guide

Troubleshooting

Webhook Events

Error envelope

Error codes

Retry strategy

Next steps