Troubleshooting

Symptom	Code	Status	Jump to
Every request rejected	`INVALID_API_KEY`	401	Authentication failures
Payment refused, credit-related	`INSUFFICIENT_CREDIT`	402	Credit and vault issues
Payment refused, screening	`AML_DECLINED`	402	AML declines
Agent blocked at a merchant	`AGENT_NOT_ALLOWLISTED`	403	Allowlist issues
Requests throttled	`RATE_LIMITED`	429	Rate limiting
Payment on a stale order	`ORDER_EXPIRED`	400	Expired orders
Payment stuck in `pending`	—	—	Settlement delays
Events never arrive	—	—	Webhooks not received

401 INVALID_API_KEY — authentication failures

Cause: The key is wrong, revoked, or — most commonly — a key from one environment sent to the other’s base URL. Sandbox keys (sk_test_) only work against https://api-sandbox.sohopay.xyz/v1; mainnet keys (sk_live_) only against https://api.sohopay.xyz/v1.Recovery:

Check the key prefix against the base URL you are calling. This mismatch causes the large majority of 401s.
Confirm the header is exactly Authorization: Bearer sk_test_... — no quotes, no missing Bearer.
Check the dashboard under Settings → API Keys that the key still exists and was not rotated or revoked.
If it was rotated, update your secrets manager and redeploy. See Authentication & Security.

402 INSUFFICIENT_CREDIT — credit and vault issues

Cause: The payment amount exceeds the agent’s available_credit. Credit is backed by vault collateral, and is consumed by outstanding (not-yet-repaid) spend and capped by the agent’s daily_limit.Recovery:

Read the agent (GET /agents/{id}) and compare available_credit to the order amount. Also check whether today’s spend has hit daily_limit.
Check the operator’s vault balance in the Wallet Usage dashboard — borrowing capacity equals vault collateral.
Unwind outstanding credit (repay), deposit more collateral via vault.deposit, or raise the agent’s credit_limit / daily_limit with agents.update if collateral allows. See Vault Funding.

403 AGENT_NOT_ALLOWLISTED — allowlist issues

Cause: The merchant enforces an on-chain allowlist and this agent’s wallet is not on it. The Policy Service fails closed, so the payment is refused before signing.Recovery:

The merchant adds the agent via merchants.allowlist.add (or the dashboard).
Allowlist changes are on-chain — allow roughly one block (~2s on Base) before retrying. A retry immediately after the add can still 403.
Verify with merchants.allowlist.list, then resubmit the payment.

If the code is AGENT_REVOKED instead, the agent was revoked by its operator and cannot be re-enabled — create a new agent.

429 RATE_LIMITED — rate limiting

Cause: You exceeded per-key or per-agent rate limits. The response carries Retry-After (seconds) plus X-RateLimit-Limit and X-RateLimit-Remaining.Recovery: Honor Retry-After, then back off exponentially. The official SDKs do this automatically; if you call the API directly:

async function withBackoff<T>(fn: () => Promise<Response>, max = 5): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await fn();
    if (res.status !== 429 || attempt >= max) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

Retries are safe because every POST carries an Idempotency-Key. If you hit limits under normal load, request a per-agent limit increase via support.

402 AML_DECLINED — AML declines

Cause: Didit wallet screening flagged the agent or counterparty wallet. The Policy Service fails closed, so no settlement occurs. You also receive an agent.aml_declined webhook.Recovery:

Check the agent’s status and screening detail in the dashboard.
If you believe it is a false positive, appeal via support with the agent_id, request_id, and any documentation of the wallet’s provenance. Appeals resolve in 24–48 hours.
If the decline stands, create a new agent with a clean wallet — SohoPay provisions the wallet inside MPC, so a fresh agent gets a fresh address. See AML Screening.

In sandbox, AML_DECLINED is only triggered deliberately via the designated test wallets — see Testing.

400 ORDER_EXPIRED — expired orders

Cause: Orders live 10 minutes. A payment submitted after the TTL is rejected — the EIP-712 authorization it would sign is time-bound, so expired orders can never be revived.Recovery:

Recreate the order with orders.create (same parameters are fine) and submit the payment against the new order_id.
If this recurs, move order creation closer to payment time — create the order when the agent decides to pay, not when it starts browsing.

Settlement delayed — payment stuck in pending

Cause: Normal finality on Base is ~1 second; sandbox usually settles under 2 seconds. Longer delays mean Base network congestion or a Policy Service disruption — SohoPay is fail-closed, so a Policy Service outage pauses settlements rather than skipping checks.Recovery:

Check the Observatory for current settlement latency and any active incident.
Check the platform status endpoint (GET /status) for degraded components.
Do not resubmit — the payment is queued and settles automatically on recovery; idempotency prevents double-settlement anyway.
If a payment is pending beyond a few minutes with no incident posted, contact support with the payment_id and, if present, the settlement_tx hash. SLA terms are in SLA.

Webhook not received — events never arrive

Cause: Your endpoint is unreachable, too slow, returning non-2xx, or rejecting deliveries during signature verification. SohoPay counts anything other than a fast 2xx as a failure and retries at 5s, 30s, 2m, 10m, 1h, then hourly up to 24h.Recovery:

Confirm the endpoint returns 2xx quickly (under a few seconds). Acknowledge first, process asynchronously.
Check your signature verification: it must use the raw request body (not re-serialized JSON) with the Sohopay-Signature and Sohopay-Timestamp headers. See Webhooks.

Fire a test delivery and watch your logs:

curl -X POST https://api-sandbox.sohopay.xyz/v1/webhooks/whk_1a2b3c4d/test \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Still nothing? Point the webhook at webhook.site temporarily — if deliveries appear there, the problem is on your endpoint, not SohoPay’s sender.
Remember deliveries can arrive out of order and more than once — dedupe by event_id.

Error Reference

Every error code, envelope shape, and HTTP status.

Error Handling Guide

Retry, backoff, and recovery patterns in depth.

Best Practices

Prevent these issues before they happen.

Help

Troubleshooting

Quick lookup

Next steps

Error Reference

Error Handling Guide

Best Practices

​Quick lookup

​Next steps

Error Reference

Error Handling Guide

Best Practices

Quick lookup

Next steps