Errors and safe retries
Distinguish unknown outcomes from a verified terminal refusal.
The integration envelope is { "error": { "code": "INVALID_AMOUNT", "message": "Human-readable diagnostic" } }. Branch on error.code; HTTP status and prose alone are insufficient. A timeout, lost response or generic 5xx leaves creation uncertain: reuse the saved body and Idempotency-Key.
| Code | Action |
|---|---|
INVALID_REQUEST, INVALID_AMOUNT | Correct fields; v2 amountUsd/baseAmountUsd require positive plain decimal strings with at most 18 integer and 6 fractional digits; 25.0000001 is rejected. No signs/exponents/whitespace/leading zeroes. |
INVALID_API_KEY | Verify secret, project and mode; keep credentials private. |
PROJECT_NOT_READY, WALLET_NOT_CONFIGURED | Complete project setup and compatible wallet/route requirements; check account eligibility. |
UNSUPPORTED_ASSET, UNSUPPORTED_NETWORK | Use an offered route for this context. |
INVOICE_NOT_FOUND | Check ID and project/context; this legacy code may also cover a missing session. |
IDEMPOTENCY_CONFLICT | Reconcile saved identity/body/external order; do not bypass with a new key. |
DEMAND_MONITORING_UNAVAILABLE, TEMPORARILY_UNAVAILABLE | Back off; preserve request identity. |
AMOUNT_SPACE_EXHAUSTED | Routing capacity unavailable; contact support, never invent an exact amount. |
RATE_LIMITED | Respect supplied retry metadata and use backoff with jitter. |
429 may include resourceCode, scope, limit, profile, retryAfterSeconds, retryable. Quotas depend on configuration; no universal request limit is promised.
Terminal creation refusal
Only a fully validated error with code: "PAYMENT_CREATION_DECLINED", version: 1, retryable: false, sessionCreated: false, a valid rejectionId, and matching projectId, mode, externalId, idempotencyKey, requestHash establishes a committed no-session refusal. Verify all identity fields against the saved request and preserve the receipt. A bare HTTP 503, missing field or mismatched identity remains uncertain; do not create a replacement using a fresh identity.
Expiry is not final unpaid proof. Inspect status, monitoringComplete, pendingSettlement and isFinal. Wrong, additional or late transfers require investigation; never automatically ask for another transfer or promise a refund.