Errors

Every 4xx/5xx response carries the same JSON envelope:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" }
  ]
}

• code — the numeric HTTP status (400, 401, 404, …). Useful for generic HTTP-layer handling, but for branching logic switch on message instead — code won’t disambiguate between, say, invalid_input and payment_method_not_supported (both 400).
• message — the lower-snake-case sentinel name, the sentinel name in lower snake case (e.g. INVALID_INPUT becomes "invalid_input"). Stable across releases — switch on this.
• details — populated on validation errors. Array of { field, message } objects so the client can pin errors to inputs. Omitted otherwise.

{ "error": "unauthorized", "message": "invalid signature" }

HTTP status → typical codes

Full code reference

The code values you may see:

Authentication (401)

• INVALID_CREDENTIALS — API key combination rejected
• INVALID_TOKEN — token unparseable or tampered
• TOKEN_EXPIRED — token expired
• SESSION_EXPIRED — dashboard session expired
• INVALID_SIGNATURE — HMAC signature mismatch on B2B / webhook calls

Authorization (403)

• FORBIDDEN — authenticated, but you aren’t allowed to perform this action
• IP_BLOCKED — requests from this IP address are blocked

Not found (404)

• NOT_FOUND — generic
• RECORD_NOT_FOUND — row missing for the given ID

Conflict (409)

• ALREADY_EXISTS — generic

Validation (400)

• INVALID_INPUT — generic; check details
• MISSING_REQUIRED — a required field was absent
• INVALID_FORMAT — value didn’t match the expected format (e.g. UUID, URL, email)
• INVALID_LENGTH — value too short or too long
• INVALID_VALUE — value out of allowed enum/range
• PAYMENT_METHOD_NOT_SUPPORTED — provider/asset combo isn’t enabled for the merchant
• AMOUNT_BELOW_MINIMUM — order amount below the per-network or env-level floor. The response’s details.floor_usd carries the configured floor (USD) so you can surface it directly; the message text states it too.
• INSUFFICIENT_BALANCE — the buyer’s wallet doesn’t hold enough of the pay asset to cover the transfer.
• INSUFFICIENT_GAS — the buyer’s wallet lacks the native token to pay the network fee (gas) for the transfer.

Payment / billing (402)

• INSUFFICIENT_CREDIT — merchant prepaid balance can’t cover the network fee (gas) and platform fee. Top up via the dashboard, then retry

Rate limiting (429)

• TOO_MANY_REQUESTS — IP rate limit exceeded
• TOO_MANY_ATTEMPTS — repeated failed attempts on the same resource (e.g. OTP) tripped a throttle

Server errors (500)

• EXTERNAL_SERVICE_ERROR — a third-party provider failed
• INTERNAL_SERVER_ERROR — unexpected error; contact support with the response Date header and X-RateLimit-* headers

Availability (503)

• SERVICE_UNAVAILABLE — the service is temporarily unavailable; retry with backoff

Validation errors (400)

When the issue is a malformed request body, details is an array so you can map errors back to fields:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" },
    { "field": "success_url", "message": "must be a valid https URL" }
  ]
}

Auth errors (401)

INVALID_SIGNATURE has three common causes:

• Wrong secret key (re-check env var)
• Timestamp drift > 5 min (sync NTP)
• Wrong canonical string (most often: forgot \n separators, or signed a parsed-then-re-stringified body that differs from what you sent)

See Authentication for the exact signing algorithm.

Rate limits (429)

X-RateLimit-Limit and X-RateLimit-Remaining are included on every rate-limited response, not just successful ones. Treat them as the live budget for your IP.

Rate-limited responses include a Retry-After header (seconds until the window resets) — honor it. As a fallback, back off with jitter — 1s base + exponential to 30s.

Insufficient credit (402)

INSUFFICIENT_CREDIT (HTTP 402 Payment Required) means your prepaid balance can’t cover the network fee (gas) and platform fee for the operation you tried to perform, typically settling a crypto payment or an on-chain action whose network fee is sponsored. Top up from the merchant dashboard (Billing → Add credit), then retry the operation. Operations already in progress continue automatically once the balance is topped up.

Server errors (5xx)

A 500 means we couldn’t process the request. Retry with backoff — your idempotency_key ensures you won’t double-charge if the original request did partially succeed.

If retries don’t recover within a minute, surface a generic “payment temporarily unavailable” to the buyer and reach out to support with the failing endpoint, your merchant ID, the response Date header and X-RateLimit-* values, and the approximate request time — that’s enough for us to find the request.

Webhook delivery errors

Webhook deliveries are a separate failure channel — they don’t surface as API errors because your server isn’t the one calling. When a delivery returns a non-2xx (or times out), it’s retried with exponential backoff at 0s, 1min, 5min, 15min, 1h, 6h (six attempts total, the same schedule as Webhooks → Overview). The full per-delivery history shows up under Developers → Webhooks → [endpoint] → Delivery log in the dashboard. After the sixth attempt the delivery is marked “Failed” in the dashboard, and you can replay it manually once your server is healthy.