Errors

The API returns errors in three different JSON shapes. Which one you get depends on the endpoint and on how the failure was raised, not on the status code. Write one parser that handles all three before you write anything else.

The three error bodies

{ "error": "amount must be positive" }

{
  "error": {
    "message": "Agent has no spend limit for this asset",
    "code": "payout_controls_required"
  }
}

{
  "errors": [
    "Url is not a valid URL",
    "Subscribed events can't be blank"
  ]
}

Shape	Where you get it
`{"error": "<string>"}`	The majority of endpoints. Hand-written guard clauses on the endpoint itself.
`{"error": {"message", "code"}}`	Generic error handling (404, 422, 502, 500), every `/agentic/*` endpoint, platform endpoints, and some payout and balance-swap paths.
`{"errors": ["…", "…"]}`	Validation failures: webhook endpoints, payout schedules, billing creates and updates, custom domains, OAuth apps.

Two things follow from this that surprise people:

error is sometimes a string and sometimes an object. error.message throws on most 4xx responses. Check the type first.
code is frequently null. Every generically handled exception renders {"error": {"message": "…", "code": null}}. Only hand-written failures set a code. Never key your control flow on code alone.

Normalizing all three

southpay/errors.ts

export type SouthPayError = { message: string; code: string | null };

export function readError(body: unknown): SouthPayError {
  const b = body as Record<string, unknown> | null;

  if (typeof b?.error === "string") {
    return { message: b.error, code: null };
  }

  if (b?.error && typeof b.error === "object") {
    const e = b.error as { message?: string; code?: string | null };
    return { message: e.message ?? "Unknown error", code: e.code ?? null };
  }

  if (Array.isArray(b?.errors)) {
    return { message: (b.errors as string[]).join("; "), code: null };
  }

  return { message: "Unknown error", code: null };
}

The OAuth endpoints (/oauth/authorize, /oauth/token, /oauth/revoke) use the RFC 6749 shape, which looks identical to the plain-string shape but means something different: {"error": "invalid_request", "error_description": "code_challenge is required"}. There, the error string is the machine code and the human text is in error_description. Branch on the endpoint, not on the body.

Status codes

Status	When
`200 OK`	Request succeeded
`201 Created`	Resource created
`202 Accepted`	A report is still generating. Poll `GET /reports` for the URL.
`204 No Content`	Delete succeeded (webhook endpoints, payout schedules). Empty body.
`400 Bad Request`	OAuth protocol errors, or a missing `X-Store-Id` on a dashboard session. Rare on the rest of the API.
`401 Unauthorized`	Missing, malformed, revoked or expired credential
`403 Forbidden`	The most common failure in this API. Missing scope, ungated feature, missing mandate, exceeded spend cap, or a platform guardrail.
`404 Not Found`	The record does not exist inside your store and mode
`409 Conflict`	Duplicate customer email, duplicate payout address, a retry already running, verification already pending
`410 Gone`	An onboarding link that has expired or been used
`422 Unprocessable Entity`	Validation failure or a business rule refusal. The default failure code.
`429 Too Many Requests`	Rate limited. See Rate limits.
`500 Internal Server Error`	Unhandled exception. Safe to retry.
`502 Bad Gateway`	A payment or payout provider failed. Safe to retry.
`503 Service Unavailable`	A swap quote is unavailable, or the identity provider is down during a step-up check.

There is no 409 for idempotency. SouthPay does not detect “same key, different body”. See Idempotency.

403 is not an authentication problem

A 403 means your credential is valid and the request was refused. Six distinct causes produce one status code, and only the code tells them apart. This is the single most useful thing to log.

Code	Cause	Fix
`insufficient_scope`	The credential lacks the scope for this resource and verb	Reissue the key with the scope. See Authentication.
`publishable_key_forbidden`	A `sp_pk_` key called anything other than `POST /payments`	Use a secret key server-side
`not_a_platform`	Platform endpoints, or `X-Southpay-Account`, on a store where platform mode is not enabled	SouthPay staff must enable it. See Platform accounts.
`account_not_found`	`X-Southpay-Account` names a store that is not your sub-merchant	Check the account id
`platform_cannot_issue_credentials`	A platform tried to manage a sub-merchant’s API keys or agent credentials while acting as them	Not permitted, by design
`platform_cannot_change_payout_destination`	A platform tried to change a sub-merchant’s payout destination	Only the merchant can, through an onboarding link
`mandate_required`	An agentic refund, token toggle, mandate issuance or x402 settlement with no usable mandate	See Agent authorization
`payout_controls_required`	An agentic payout with no spend limit configured for that asset	Configure a spend limit on the agent credential
`authorization_denied`	The store’s authorization provider refused the agentic action	Inspect the mandate
`per_tx_cap_exceeded` / `daily_cap_exceeded`	The agent credential’s spend limit was hit	Raise the cap or wait for the UTC day to roll
`spend_cap_exceeded`	An x402 mandate’s per-call cap or remaining envelope was exhausted	Issue a new mandate

mfa_required, otp_required, otp_invalid, mfa_check_unavailable and otp_check_unavailable also return 403 (or 503), but only for logged-in dashboard sessions. API keys, OAuth tokens and agent credentials never trigger the step-up check, so an integration will not see them.

Error codes by status

Every code below appears in the API source. If you see a code that is not here, treat it as null.

401

Code	Meaning
`invalid_api_key`	The `sp_` key is unknown, revoked, or in the wrong mode
`invalid_token`	The `spo_` OAuth token is unknown, revoked, or expired
`agent_credential_required`	An `/agentic/*` call arrived without a `spa_` credential
`invalid_agent_credential`	The `spa_` credential is unknown, revoked, or expired

404 and 410

Code	Status	Meaning
`not_found`	404	Agentic mandate, payout or settlement lookup missed
`asset_not_found`	404	The `asset_id` is not one SouthPay supports
`token_not_found`	404	Market data has no such token
`account_not_found`	404	A platform account id in the path does not resolve
`onboarding_link_unusable`	404 / 410	Onboarding token is unknown, consumed, or expired

Most 404s carry no code at all. A record that does not resolve renders {"error": {"message": "Couldn't find …", "code": null}}.

409

Code	Meaning
`retry_in_progress`	A payout retry is already running
`verification_already_pending`	A verification request is already under review
`duplicate_address`	The payout address is already registered on this account
`store_has_active_funds`	A store delete was blocked. The body adds a `blockers` array.

Duplicate billing customers return 409 with the plain-string body {"error": "A customer with this email already exists"} and no code.

422

Code	Meaning
`idempotency_key_required`	The endpoint requires an `Idempotency-Key` header. See Idempotency.
`invalid_amount`	Amount is zero, negative, non-finite, or has more than two decimal places
`amount_too_large`	Agentic payment above 100,000,000.00
`invalid_currency` / `unsupported_currency`	Not one of the supported fiat currencies
`invalid_metadata`	More than 50 keys, or a non-string value
`not_cancelable`	The intent is not `pending`, so it cannot be canceled
`destination_required`	A payout has neither a payout detail id nor a `destination_address`
`payout_rejected`	Insufficient balance or below the asset minimum
`insufficient_balance`	An x402 settlement exceeds the store balance
`not_retryable`	The payout is not in a retryable state
`no_route`	No swap route exists between the two assets
`invalid_cap` / `mandate_ref_required`	Mandate issuance is missing a positive cap or a `mandate_ref`
`asset_change_rejected`	The agent’s token toggle was refused
`invalid_account` / `invalid_onboarding_link`	Platform account or onboarding link payload is invalid
`invalid_verification` / `invalid_payout_destination`	Onboarding submission is invalid
`missing_parameter`	Market data called without `symbol_or_id`
`store_required`	The OAuth-to-agent-credential exchange had no store on the grant

Most 422s carry no code. They are plain strings such as "amount is required and must be positive" or "metadata values must be strings", or a {"errors": [...]} list from a model validation. The report endpoints are a special case: they return 422 with a bare string in error plus a sibling field. {"error": "date_range_too_large", "max_days": 366} and {"error": "date_range_unavailable", "available_through": "2026-08-05"}.

429, 502 and 503

Code	Status	Meaning
`rate_limited`	429	A rate limit was exceeded. See Rate limits.
`too_many_failed_attempts`	429	Too many requests from your address failed authentication
`upstream_rate_limited`	429	The market data provider throttled us
`market_data_error`	502	The market data provider failed
`quote_unavailable`	503	No swap quote could be obtained

502 from a payment or payout provider is always {"error": {"message": "Payment provider error", "code": null}}. The real cause is logged on our side; open a support ticket with the request timestamp rather than parsing the message.

Rate limits

Most of the API is not throttled today. POST /api/v2/payments, the checkout and onramp reads, the OAuth endpoints and the agentic surface are. Each is a token bucket, every 429 carries Retry-After in seconds, and authenticated responses carry your remaining budget. See Rate limits for the full table, how each limit is keyed, and the two 429 body shapes.

What to retry

Status	Retry	Notes
`429`	Yes	Wait the number of seconds in `Retry-After`.
`500`	Yes	Exponential backoff, same `Idempotency-Key`
`502`	Yes	Provider hiccup. Exponential backoff, same `Idempotency-Key`.
`503`	Yes	Quote or identity check unavailable. Backoff.
Network timeout	Yes	Same `Idempotency-Key`. The request may already have landed.
`4xx` other than `429`	No	Fix the request. Retrying returns the same error.

Reusing the Idempotency-Key is what makes a retry safe. A replay returns the record that the first attempt created rather than creating a second one. See Idempotency for what that does and does not guarantee.

southpay/request.ts

import { readError } from "./errors";

const RETRYABLE = new Set([429, 500, 502, 503]);

export async function request(path: string, init: RequestInit, idempotencyKey?: string) {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${process.env.SOUTHPAY_API_KEY}`,
    "Content-Type": "application/json",
    ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
  };

  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(`https://api.southpay.io${path}`, { ...init, headers });
    if (res.ok) return res.json();

    if (!RETRYABLE.has(res.status) || attempt === 3) {
      const err = readError(await res.json().catch(() => null));
      throw Object.assign(new Error(err.message), { status: res.status, code: err.code });
    }

    await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
  }
}

Getting started

Authentication

Core resources

Recurring

Checkout

Agentic commerce

Platform

Integrations

Building reliably

Changelog

The three error bodies

Normalizing all three

Status codes

403 is not an authentication problem

Error codes by status

401

404 and 410

409

422

429, 502 and 503

Rate limits

What to retry

​The three error bodies

​Normalizing all three

​Status codes

​403 is not an authentication problem

​Error codes by status

​401

​404 and 410

​409

​422

​429, 502 and 503

​Rate limits

​What to retry

The three error bodies

Normalizing all three

Status codes

403 is not an authentication problem

Error codes by status

401

404 and 410

409

422

429, 502 and 503

Rate limits

What to retry