> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & responses

> The response envelope, status codes, and error codes for the v3 API.

## Response envelope

Every JSON response uses a consistent envelope.

**Success:**

```json theme={null}
{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}
```

**Error:**

```json theme={null}
{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found"
}
```

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:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [ /* … */ ],
    "pagination": { "nextCursor": "eyJ…", "hasMore": true }
  }
}
```

Pass `?limit=` (1–100, default 20) and `?cursor=` (the previous
`pagination.nextCursor`). When `hasMore` is `false`, `nextCursor` is `null`.

## HTTP status codes

| Status | Meaning                                               |
| ------ | ----------------------------------------------------- |
| `200`  | OK                                                    |
| `201`  | Created                                               |
| `204`  | No Content (successful delete)                        |
| `400`  | Bad request (e.g. invalid checkout-session signature) |
| `401`  | Missing or invalid API key                            |
| `404`  | Resource not found                                    |
| `422`  | Validation error (see `data.fieldErrors`)             |
| `429`  | Rate limited — back off and retry                     |
| `5xx`  | Server error                                          |

## Validation errors

A `422 VALIDATION_ERROR` includes per-field detail:

```json theme={null}
{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": {
    "fieldErrors": [
      { "field": "method", "message": "method is a required field" }
    ]
  }
}
```

## 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](/v3-beta/idempotency).

## Domain-specific error codes

<AccordionGroup>
  <Accordion title="Payments">
    `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`.
  </Accordion>

  <Accordion title="Subscriptions">
    `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`.
  </Accordion>

  <Accordion title="Products">
    `PRODUCT_NOT_FOUND`, `PRODUCT_OUT_OF_STOCK`, `PRODUCT_ARCHIVED`,
    `RECURRING_REQUIRES_INTERVAL`.
  </Accordion>

  <Accordion title="Customers & payment methods">
    `CUSTOMER_NOT_FOUND`, `CUSTOMER_ALREADY_EXISTS`,
    `CUSTOMER_PAYMENT_METHOD_NOT_FOUND`, `CUSTOMER_PAYMENT_METHOD_REVOKED`.
  </Accordion>

  <Accordion title="Payouts">
    `PAYOUT_NO_ROUTE`, `PAYOUT_NO_PAYOUT_ACCOUNT`,
    `PAYOUT_INSUFFICIENT_WITHDRAWABLE`, `PAYOUT_RAIL_UNAVAILABLE`,
    `PAYOUT_MOR_NOT_SUPPORTED`, `PAYOUT_NOT_FOUND`.
  </Accordion>

  <Accordion title="Setup intents">
    `SETUP_INTENT_NOT_FOUND`, `SETUP_INTENT_CUSTOMER_NOT_FOUND`,
    `SETUP_INTENT_PROVIDER_ERROR`.
  </Accordion>

  <Accordion title="Checkout sessions">
    `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`.
  </Accordion>

  <Accordion title="Checkout settings & webhook endpoints">
    `SUBY_BADGE_NOT_REMOVABLE`, `WEBHOOK_ENDPOINT_NOT_FOUND`.
  </Accordion>
</AccordionGroup>