Error Reference

This page lists all error codes returned by the Breeze API, organized by the section of the integration where they appear. All errors are returned in a consistent envelope:

{
  "status": "FAILED",
  "errorCode": "<ERROR_CODE>",
  "errorMessage": "<human-readable message>"
}

UserError codes indicate a problem with the request (HTTP 400). ServerError codes indicate an unexpected failure on Breeze's side (HTTP 500) — these are safe to retry.

Quick Start

These errors can be returned when creating a payment page via POST /v1/payment_pages with inline product details.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`MISSING_PARAMETER`	A required field is absent.
`AMOUNT_TOO_SMALL`	The total amount is below the minimum of 100 minor units (e.g. $1.00 USD).
`AMOUNT_TOO_LARGE`	The total amount exceeds the maximum allowed value.
`NOT_SUPPORTED`	A line item references a subscription-type product. Only `REGULAR` products are supported in payment page line items.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Malformed billing email	The `billingEmail` field is not a valid email address.
Missing line items	The `lineItems` array is absent or empty.
Missing `clientProductId`	When providing inline product details, `clientProductId` is required for each line item.
Product or price not found	A `product` or `priceId` referenced in a line item does not exist.
Invalid `clientReferenceId`	The value contains disallowed characters; only alphanumeric characters and hyphens are permitted.
Unsupported currency	The specified `currency` is not supported.
Invalid quantity	`quantity` must be greater than 0.

Payin

These errors can be returned when creating, retrieving, or expiring a payment page, or when initiating or retrieving a refund via the /v1/payment_pages endpoints.

API Errors

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`PAYMENT_PAGE_NOT_FOUND`	No payment page exists with the given ID, or it belongs to a different merchant account.
`WRONG_PARAMETER`	A field value is invalid.
`MISSING_PARAMETER`	A required field is absent.
`AMOUNT_TOO_SMALL`	The total amount is below the minimum of 100 minor units (e.g. $1.00 USD).
`AMOUNT_TOO_LARGE`	The total amount exceeds the maximum allowed value.
`OPERATION_REJECTED`	The expire request was blocked because a crypto payment or card capture is currently in progress on this page.
`RESOURCE_NOT_FOUND`	No refund record was found for the given refund ID on this payment page.
`NOT_SUPPORTED`	A line item references a subscription-type product. Only `REGULAR` products are supported in payment page line items.
`REFUND_NOT_ALLOWED`	The payment cannot be refunded. Possible causes: the payment is not in `PAID` status; the payment method is not a card; the refund window has elapsed; or the payment has already been fully refunded.
`REFUND_ALREADY_EXISTS`	A refund has already been initiated for this payment.
`DB_QUERY_DOCUMENT_FAILED`	A Firestore read failed while retrieving the payment page. Retry the request; if the issue persists, contact support.
`DB_UPDATE_DOCUMENT_FAILED`	A Firestore write failed while updating the payment page. Retry the request; if the issue persists, contact support.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Malformed billing email	The `billingEmail` field is not a valid email address.
Missing line items	The `lineItems` array is absent or empty.
Missing `clientProductId`	When providing inline product details, `clientProductId` is required for each line item.
Product or price not found	A `product` or `priceId` referenced in a line item does not exist.
Invalid `clientReferenceId`	The value contains disallowed characters; only alphanumeric characters and hyphens are permitted.
Unsupported currency	The specified `currency` is not supported.
Invalid quantity	`quantity` must be greater than 0.
Invalid status for expire	The payment page is not in `UNPAID` status and cannot be expired.

Decline Codes

These codes appear as the errorCode field inside PAYMENT_ATTEMPT_FAILED webhook event payloads. They indicate why a specific payment attempt was rejected and are distinct from API response errors.

Issuer / provider declines — the card was declined by the issuing bank or payment processor. The customer should verify their card details or try a different card.

Error code	Description
`ISSUER_DECLINE`	The issuing bank declined the transaction for an unspecified reason.
`ISSUER_DECLINE_FRAUD`	The issuing bank declined due to suspected fraud on the card.
`ISSUER_DECLINE_LIMIT`	The issuing bank declined because a transaction, daily, or account limit was exceeded.
`ISSUER_DECLINE_RESTRICTED_CARD`	The card is restricted and cannot be used for this type of transaction.
`ISSUER_DECLINE_RISK`	The issuing bank declined based on its own internal risk assessment.
`ISSUER_DECLINE_SECURITY_VIOLATION`	The issuing bank declined due to a security policy violation.
`ISSUER_DECLINE_TRANSACTION_NOT_PERMITTED`	This transaction type is not permitted for the card.
`INSUFFICIENT_FUNDS`	The card has insufficient funds to cover the transaction amount.
`EXPIRED_CARD`	The card has expired. The customer should use a new card.
`INCORRECT_CARD_DETAILS`	The card number, expiry date, or CVV provided is incorrect.
`INVALID_CARD`	The card number is invalid or not recognised.
`FAILED_3DS`	3D Secure authentication failed. The customer should retry or use a different card.
`PARTNER_ERROR`	The payment processor returned an unspecified error. Retry the transaction.

Breeze risk declines — the transaction was blocked by Breeze's internal risk engine.

Error code	Description
`RISK_GENERAL`	The transaction was blocked by Breeze's risk engine for a general risk signal.
`RISK_SOFT`	A soft risk flag was triggered; the transaction was declined as a precaution.
`RISK_HARD`	A hard risk block was triggered. This card or account cannot complete transactions at this time.
`RISK_HARD_RECEIVED_CHB`	Blocked because a prior chargeback was received on this account.
`RISK_HARD_RECEIVED_FRAUD`	Blocked because prior fraud was reported on this account.
`RISK_NAME_MISMATCH`	The cardholder name does not match the name on the Breeze account.
`RISK_ONGOING_CHECK`	The transaction is under an ongoing compliance or fraud review.
`RISK_SHARED_CARD`	The card has been used across multiple accounts, triggering a shared-card fraud signal.
`RISK_CARD_TYPE_NOT_ALLOWED`	The card type (e.g. prepaid, corporate) is not permitted for this merchant.

Location and compliance declines

Error code	Description
`RESTRICTED_LOCATION`	The transaction was declined because the customer's detected location is not supported.
`CARD_COUNTRY_NOT_ALLOWED`	The card was issued in a country that is not supported.
`BANK_COUNTRY_NOT_ALLOWED`	The bank country associated with the card is not supported.
`COMPLIANCE_REASONS`	The transaction was declined due to compliance requirements. Contact support for details.
`AGE_RESTRICTION`	The transaction was declined because the customer does not meet the minimum age requirement.

Other

Error code	Description
`DUPLICATE_CONCURRENT_PAYMENT`	A duplicate or concurrent payment attempt was detected for this page.
`APPLICATION_ERROR`	An error occurred in the payment application layer. Retry the transaction.
`PAYMENT_FAILED`	The payment attempt failed for an unspecified reason.

Fallback codes — these appear when no specific decline code is available, typically for non-card payment methods (ACH, crypto) or legacy flows.

Error code	Description
`PAYMENT_DECLINED_PROVIDER`	The payment was declined by the payment processor.
`PAYMENT_DECLINED_RISK`	The transaction was blocked by Breeze's internal risk engine.
`PAYMENT_DECLINED_GEOLOCATION`	The transaction was declined because the customer's location is not supported.
`PAYMENT_DECLINED_BILLING`	The transaction was declined due to a billing address or billing detail mismatch.
`PAYMENT_DECLINED_GPS`	The transaction was declined due to a GPS or location-based restriction.
`PAYMENT_DECLINED_FRAUD`	The transaction was flagged and declined due to suspected fraud.
`PAYMENT_DECLINED_NEW_USER_MONITOR`	The transaction was held for review under new-user monitoring rules.

Payout Page

These errors can be returned when creating, retrieving, releasing, or cancelling a payout page via the /v1/payout_pages endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`PAYOUT_PAGE_INVALID_MERCHANT_SETTINGS`	The merchant account is not configured to accept payout pages. Possible causes: no fee configuration found; escrow settings are missing for the requested funding network. Contact support to resolve.
`OPERATION_REJECTED`	Payout page creation was blocked by Breeze's risk engine.
`DB_DOCUMENT_ALREADY_EXISTS`	The `clientReferenceId` has already been used for another payout page. Use a unique value.
`PAYOUT_PAGE_NOT_FOUND`	No payout page exists with the given ID, or it belongs to a different merchant account.
`PAYOUT_PAGE_CANNOT_RELEASE`	The payout page cannot be released. Possible causes: the payout page is not in `PENDING` status with a `pendingStatus` of `PENDING_MERCHANT_RELEASE`; or the payout page's release method is not `MANUAL`.
`PAYOUT_PAGE_CANNOT_CANCEL`	The payout page cannot be cancelled. The payout page must be in `CREATED` or `PENDING` status to be cancelled.
`PAYOUT_PAGE_CANNOT_INITIATE`	The payout could not be initiated after release. Possible causes: the user's KYC or compliance checks failed; the selected payout method failed its pre-initiation checks.
`PAYOUT_PAGE_STATUS_INVALID`	The payout page is not in the expected status for the release method in use. Retry the request; if the issue persists, contact support.
`RESOURCE_BUSY`	The payout page is currently being processed by another operation. Wait a moment and retry.
`USER_DAILY_TOTAL_PAYOUT_AMOUNT_LIMIT_EXCEEDED`	The user has exceeded the daily total payout amount limit. The request cannot be processed until the limit resets. Contact support if you believe this is incorrect.
`TRANSFER_INSUFFICIENT_BALANCE`	The payout could not be completed because the merchant's payout escrow has insufficient balance to fund the transfer. Top up your payout escrow and retry.
`DB_UPDATE_DOCUMENT_INVALID`	A Firestore update was rejected due to an invalid internal state. Retry the request; if the issue persists, contact support.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Unsupported funding currency	`fundingCurrency` is not a supported crypto token.
Customer not found	The specified customer does not exist or does not belong to this merchant account.
Email mismatch	The provided email does not match the email address on file for the specified customer.

Customers

These errors can be returned when creating, retrieving, updating, or offboarding a customer via the /v1/customers endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`RESOURCE_NOT_FOUND`	No customer was found with the given ID, or the customer does not belong to this merchant account.
`RESOURCE_ALREADY_EXISTS`	A customer with this email address already exists in your merchant account.
`MERCHANT_NOT_FOUND`	The merchant account associated with this API key could not be found.
`DB_QUERY_DOCUMENT_FAILED`	A Firestore read failed while retrieving the customer record. Retry the request; if the issue persists, contact support.
`DB_NEW_DOCUMENT_FAILED`	A Firestore write failed while creating the customer record. Retry the request; if the issue persists, contact support.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Customer belongs to different merchant	The specified customer does not belong to the authenticated merchant account.
Reference ID mismatch	The provided `referenceId` does not match the `referenceId` on file for the specified customer.

Products

These errors can be returned when creating, activating, or retrieving products, or when creating a price for a product via the /v2/products endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`MISSING_PARAMETER`	A required field is absent. For `REGULAR` products, `amount` and `currency` are always required.
`RESOURCE_NOT_FOUND`	The specified product could not be found — returned when activating a product or adding a price to a product that does not exist.
`RESOURCE_ALREADY_EXISTS`	A product with this `clientProductId` already exists in your merchant account.
`WRONG_PARAMETER`	A field value is invalid.
`NOT_SUPPORTED`	The requested operation is not supported for this product type (e.g. adding a `RECURRING` price to a `REGULAR` product).
`DB_NEW_DOCUMENT_FAILED`	A Firestore write failed while creating the product or price record. Retry the request; if the issue persists, contact support.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Price type mismatch	The price type (`ONE_TIME` vs `RECURRING`) does not match the product type.
Missing billing cycle config	`billingCycleConfig` is required for `RECURRING` prices but was not provided.

Payout Withdrawals

These errors can be returned when creating or retrieving a payout withdrawal via the /v1/payouts endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`RESOURCE_ALREADY_EXISTS`	A payout with this `clientReferenceId` already exists. Use a unique value.
`RESOURCE_NOT_FOUND`	No payout was found with the given ID.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Missing or malformed field	A required field is absent or in the wrong format.
Invalid currency	`currency` must be `USDC`.
Invalid amount	`amount` must be a positive integer.
Financial account not found	The `sender.financialAccountId` does not exist or does not belong to this merchant account.

Subscriptions

These errors can be returned when creating, retrieving, listing, or cancelling a subscription via the /v1/subscriptions endpoints, or when retrieving entitlements via /v1/entitlements.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`MISSING_PARAMETER`	A required field is absent.
`RESOURCE_NOT_FOUND`	The specified customer or subscription could not be found.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Product not found or inactive	The referenced product does not exist, is not active, or does not belong to this merchant account.
Price not found or inactive	The referenced price does not exist, is not active, or does not belong to the specified product.
Price missing billing cycle config	The referenced price does not have a `billingCycleConfig`.
Discounted trial currency mismatch	The `discountedTrial.priceId` price uses a different currency than the subscription price.
Discounted trial price too high	The `discountedTrial` price amount must be lower than the subscription price.
Scheduled start too soon	`startAt` must be at least 24 hours in the future.
Invalid cursor token	An invalid `cursorToken` was provided when paginating entitlements.
Subscription not cancelable	The subscription is not in a status that allows cancellation.

Statements

These errors can be returned when listing statements or downloading a statement file via the /v1/reports/statements endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`RESOURCE_NOT_FOUND`	No statement was found with the given ID, or it belongs to a different merchant account.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Invalid query parameter	A required query parameter (`type` or `accountType`) is missing or has an invalid value.
Statement not ready	The statement has not finished generating and cannot be downloaded yet.

Disputes

These errors can be returned when listing disputes via GET /v1/disputes.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Invalid status	The `status` query parameter is not a valid dispute status value.
Invalid date range	`dateRange.start` or `dateRange.end` is not a valid Unix timestamp.
Invalid pagination	`pagination.offset` or `pagination.limit` is missing or has an invalid value.

Reported Fraud

These errors can be returned when listing or retrieving fraud reports via the /v1/fraud_reports endpoints.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`RESOURCE_NOT_FOUND`	No fraud report was found with the given ID, or it belongs to a different merchant account.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Invalid `filters.email` format	The value provided for the `filters.email` search filter is not a valid email address.
Invalid date range format	`filters.fraudIssueDateRange.start` or `.end` is not in the expected `YYYY-MM-DD HH:mm:ss` format.
Invalid pagination	`pagination.limit` must be at least 1.

Tax

These errors can be returned when querying a tax rate via GET /v1/tax/tax_rate.

Error code	Description
`AUTHORIZATION_FAILED`	The API key is missing, invalid, or does not have permission for this operation.
`WRONG_PARAMETER`	A field value is invalid.
`MERCHANT_NOT_FOUND`	The merchant account associated with this API key could not be found.
`INTERNAL_ERROR`	An unexpected server-side error occurred. If this persists, contact support.

WRONG_PARAMETER: possible causes

Cause	Description
Invalid query parameters	A required parameter (`amount`, `zipCode`, or `currency`) is missing or in the wrong format.
Invalid or unrecognized zip code	The provided `zipCode` could not be used to calculate sales tax. Verify the zip code is valid.
Tax not configured	The merchant account does not have a tax product category configured. Contact support to resolve.