Errors

Errors use the same envelope as success responses, with success: false:

{
  "success": false,
  "message": "Validation failed",
  "code": "EXPECTED_AMOUNT_REQUIRED",
  "details": [{ "field": "amount", "message": "amount is required" }],
  "correlationId": "8f3c…"
}

• message is always present and human-readable.
• code (when set) is a stable string code — branch on this, not the message text.
• details for validation errors is an array of { field, message }.
• correlationId echoes your x-correlation-id request header — include it when contacting support.

HTTP status mapping

Situation	Status
Validation failure	422
Bad request	400
Missing/invalid API key, expired token	401
Forbidden / IP not allowed	403
Resource not found	404
Duplicate / conflict	409
Rate limit exceeded	429
Application error	the error's own status
Server error	500 (message hidden)
Upstream timeout / unavailable (gateway)	504 / 502

Error codes

Codes you may encounter on the integration surface:

Code	Status	Meaning
INVALID_API_KEY	401	Missing/malformed key, or env mismatch (test key on live, etc.)
IP_NOT_ALLOWED	403	Request IP isn't in the key's allowlist (message echoes the IP seen)
EXPECTED_AMOUNT_REQUIRED	422	amount required in client fee mode
MAX_ACTIVE_ADDRESSES	429	Active-address cap reached
SETTLEMENT_ACCOUNT_NOT_FOUND	404	settlementAccountId isn't yours
NO_SETTLEMENT_ACCOUNT	422	reusable requested with no active settlement wallet
INVALID_WEBHOOK_URL	422	Webhook URL failed the SSRF guard (private/loopback)
INVALID_EVENT_TYPE	422	Unsupported webhook event name
NO_WEBHOOK_URL	422	Tried to test a key webhook with no URL set

Rate-limit responses

A 429 may be a plain { "success": false, "message": "Rate limit exceeded" } with a Retry-After header (seconds). Honor Retry-After and retry with backoff.

Handling tips

• Retry 429 (after Retry-After) and 5xx/502/504 (with exponential backoff). Do not retry 4xx validation/auth errors — fix the request.
• Log correlationId on failures so support can trace a specific request.