Skip to main content

​
Response envelope

Every JSON response uses a consistent envelope. Success:
Error:
Two endpoints return non-envelope bodies: GET /v3/payments/:id/receipt.pdf (binary PDF) and GET /health (bare status JSON). A few endpoints return 204 No Content with an empty body (DELETE /v3/products/:id, DELETE /v3/customers/:id/payment-methods/:pmId).

​
Pagination

List endpoints are cursor-paginated:
Pass ?limit= (1–100, default 20) and ?cursor= (the previous pagination.nextCursor). When hasMore is false, nextCursor is null.

​
HTTP status codes

​
Validation errors

A 422 VALIDATION_ERROR includes per-field detail:

​
Universal error codes

Returned across all domains: INTERNAL_SERVER_ERROR, NOT_FOUND, BAD_REQUEST, CONFLICT, RATE_LIMITED, UNPROCESSABLE_ENTITY, UNAUTHORIZED, FORBIDDEN, TOKEN_EXPIRED, TOKEN_INVALID, MFA_REQUIRED, ORG_NOT_FOUND, MEMBERSHIP_NOT_FOUND, INSUFFICIENT_ROLE, ENVIRONMENT_MISMATCH, SANDBOX_ONLY, LIVE_ONLY, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_CONFLICT, VALIDATION_ERROR, MISSING_FIELD, INVALID_ID. IDEMPOTENCY_KEY_CONFLICT is returned when an Idempotency-Key is reused with a different request (422) or while the first request is still in flight (409) — see Idempotency.

​
Domain-specific error codes

PAYMENT_NOT_FOUND, PAYMENT_NOT_REFUNDABLE, PRODUCT_NOT_FOUND, CUSTOMER_NOT_FOUND, CUSTOMER_NAME_REQUIRED, PAYMENT_METHOD_NOT_FOUND, CRYPTO_ONLY_ORG, PROVIDER_NOT_CONFIGURED, KYB_NOT_APPROVED, INVALID_PAYMENT_STATUS_TRANSITION, PAYMENT_NOT_CAPTURABLE, PAYMENT_NOT_VOIDABLE, CRYPTO_ASSET_NOT_ACCEPTED, CRYPTO_PAYOUT_ADDRESS_MISSING, CRYPTO_PAYMENT_BELOW_MIN, CRYPTO_PRICE_FEED_UNAVAILABLE, CRYPTO_CURRENCY_NOT_SUPPORTED, BTC_NOT_AWAITING_APPROVAL, SOL_PAYER_ADDRESS_REQUIRED, SOL_RPC_UNAVAILABLE, EVM_PAYER_ADDRESS_REQUIRED, EVM_RPC_UNAVAILABLE, EVM_CONTRACT_NOT_DEPLOYED, CRYPTO_AUTOSWAP_TARGET_MISSING, CRYPTO_VAULT_NOT_PROVISIONED, CRYPTO_STABLECOIN_DISABLED, CRYPTO_VOLATILE_DISABLED.
SUBSCRIPTION_NOT_FOUND, SUBSCRIPTION_CUSTOMER_NOT_FOUND, SUBSCRIPTION_PRODUCT_NOT_FOUND, PRODUCT_NOT_RECURRING, PRODUCT_PRICE_MISSING, CUSTOMER_NAME_REQUIRED, FIRST_PAYMENT_DECLINED, SUBSCRIPTION_NOT_CANCELABLE, CRYPTO_ONLY_ORG. Plan change (POST /change-plan): SUBSCRIPTION_NOT_MODIFIABLE, TARGET_PRODUCT_NOT_FOUND, TARGET_PRODUCT_NOT_RECURRING, SAME_PLAN, PLAN_CHANGE_CURRENCY_MISMATCH, UPGRADE_REQUIRES_CARD, PLAN_CHANGE_DECLINED.
PRODUCT_NOT_FOUND, PRODUCT_OUT_OF_STOCK, PRODUCT_ARCHIVED, RECURRING_REQUIRES_INTERVAL.
CUSTOMER_NOT_FOUND, CUSTOMER_ALREADY_EXISTS, CUSTOMER_PAYMENT_METHOD_NOT_FOUND, CUSTOMER_PAYMENT_METHOD_REVOKED.
PAYOUT_NO_ROUTE, PAYOUT_NO_PAYOUT_ACCOUNT, PAYOUT_INSUFFICIENT_WITHDRAWABLE, PAYOUT_RAIL_UNAVAILABLE, PAYOUT_MOR_NOT_SUPPORTED, PAYOUT_NOT_FOUND.
SETUP_INTENT_NOT_FOUND, SETUP_INTENT_CUSTOMER_NOT_FOUND, SETUP_INTENT_PROVIDER_ERROR.
CHECKOUT_SESSION_NOT_FOUND, CHECKOUT_SESSION_EXPIRED, CHECKOUT_SESSION_INVALID_SIGNATURE, CHECKOUT_PRODUCT_INACTIVE, CHECKOUT_SUBSCRIPTION_REQUIRES_RECURRING_PRODUCT, CHECKOUT_METHOD_NOT_AVAILABLE, CHECKOUT_QUOTE_UNAVAILABLE, CHECKOUT_ASSET_NOT_ACCEPTED, CHECKOUT_ALREADY_COMPLETED, CHECKOUT_EMAIL_REQUIRED, CHECKOUT_BILLING_ADDRESS_REQUIRED, CHECKOUT_PAYMENT_FAILED.
SUBY_BADGE_NOT_REMOVABLE, WEBHOOK_ENDPOINT_NOT_FOUND.