Error Reference

The tables below describe every error_code the Bachs API returns. When an error has a code, its doc_url links to that code’s entry here, or to the guide that explains it. For the error object shape and how to handle errors, see Errors.

Sections marked Limited Access cover features that are not enabled by default. Contact support@bachs.io to request access.

General

Errors that can occur on any endpoint.

Code	Status	Cause and resolution
`BAD_REQUEST`	400	The request is malformed or has invalid parameters. Check it against the endpoint reference.
`UNAUTHORIZED`	401	No `Authorization` header, or the key is invalid or revoked. Send a valid key.
`FORBIDDEN`	403	The key is valid but lacks permission. Check your key’s permissions.
`NOT_FOUND`	404	The resource does not exist in your scope. Verify the ID and environment.
`INSUFFICIENT_BALANCE`	400	The `available_balance` will not cover the debit. `detail` states the shortfall, what was required, and what was available. Fund the balance, or wait for a pending charge to settle.
`IDEMPOTENCY_IN_PROGRESS`	409	A request with the same `Idempotency-Key` is still in flight. Retry after a short delay; the winner’s response is replayed once it lands.
`CONFLICT`	409	The request conflicts with current state, such as a duplicate. Reconcile and retry.
`VALIDATION_ERROR`	400	One or more fields failed validation. Inspect the `errors` array and correct the input.
`VALIDATION_FAILED`	422	A business rule rejected a well-formed request. Read `detail` for the rule.
`INVALID_REQUIREMENT_FIELD`	400	A field submitted on `POST /v1/accounts/{account_id}` was rejected. Inspect `errors[]` (`field`, `message`, `code`); no field from that submission was saved, though anything else in the same call (contact details, capability requests, profile changes) was applied before the fields were validated. See `payout_destination` for its rejection codes.
`TOO_MANY_REQUESTS`	429	Rate limit exceeded. Check `Retry-After` or `X-RateLimit-Reset` before retrying.
`PRECONDITION_REQUIRED`	428	A required precondition is missing. Read `detail` for what to supply.
`TOTP_STEP_UP_REQUIRED`	428	This action needs two-factor verification. Complete step-up and retry.
`IMMUTABLE_FIELD`	400	A field that cannot change after creation was included in an update. Remove it.
`INTERNAL_SERVER_ERROR`	500	Unexpected server-side failure. The request was not processed. Retry shortly.
`NOT_IMPLEMENTED`	501	The operation is not yet supported.
`BAD_GATEWAY`	502	An upstream dependency is temporarily unavailable. Retry shortly.
`SERVICE_UNAVAILABLE`	503	The service is temporarily overloaded or in maintenance. Retry shortly.

Payments

Encountered when initiating or processing payments.

Code	Status	Cause and resolution
`PAYMENT_ERROR`	400	A general payment processing error. Read `detail` for the cause.
`PAYMENTS_NOT_ENABLED`	400	Payments are not enabled for your organization. Complete onboarding or contact support.
`PAYMENT_METHOD_NOT_ENABLED`	400	The selected method is not enabled. Use an enabled method or contact support.
`CARD_TOKEN_INVALID`	400	The card token is invalid or expired. Collect the card again for a fresh token.
`CARD_VAULT_UNAVAILABLE`	500	The card service could not be reached. Retry shortly.
`PAYMENT_METHOD_SETUP_FAILED`	500	Payment method setup could not start. Retry shortly.
`OFF_SESSION_CHARGE_FAILED`	500	The off-session charge could not be created. Retry, or fall back to an on-session payment.
`OFF_SESSION_NOT_SUPPORTED`	400	This payment method cannot be charged off-session. Use an on-session flow.
`NO_SAVED_PAYMENT_METHOD`	400	The customer has no saved card to charge. Save one on a checkout first. See Charge a saved card.
`SAVED_PAYMENT_METHOD_NOT_FOUND`	404	No saved card with that `pm_` id belongs to this customer. Cards are scoped to one customer.
`PAYMENT_METHOD_UNUSABLE`	400	The saved card has expired or been removed. Ask the customer to save a new one.
`CHECKOUT_CANNOT_SAVE_PAYMENT_METHOD`	400	Saving a card needs a card on the checkout. This one offers no card method, so nothing could be saved. See Why a checkout cannot save a card.
`GATEWAY_UNAVAILABLE`	500	Our payment processing infrastructure is temporarily unreachable. Rare. Retry shortly, contact support if it persists.
`PROVIDER_ERROR`	500	Our payment processing infrastructure returned an unexpected error. Retry shortly.

Products & Prices

Encountered when creating or updating products and prices.

Code	Status	Cause and resolution
`PRODUCT_NOT_FOUND`	400	A referenced product does not exist or is archived. Verify the product ID.
`PRODUCT_NO_PRICE`	400	The product has no price in the requested currency. Add a price in that currency.
`PRODUCT_ARCHIVED`	400	The product is archived and cannot be used for new checkouts. Unarchive or use another.
`PRICE_REQUIRED`	400	At least one price is required. Include a price on the product.
`MINIMUM_PRICE_REQUIRED`	400	A product must keep at least one price. You cannot remove the last one.
`DUPLICATE_CURRENCY`	400	A price for this currency already exists. Update the existing price instead.
`UNSUPPORTED_CURRENCY`	400	The currency is not in the active supported set. Use a supported currency.
`INTERVAL_REQUIRED`	400	`interval_count` requires a positive integer when `interval` is set. Supply both.
`INTERVAL_NOT_ALLOWED`	400	`interval_count` was provided without an `interval`. Add an `interval` or remove the count.
`INVALID_INTERVAL`	400	`interval` must be one of `day`, `week`, `month`, or `year`.
`RECURRING_INTERVAL_IMMUTABLE`	400	`recurring_interval` cannot change once set. Create a new product instead.
`TRIAL_REQUIRES_RECURRING`	400	A trial is only valid on a recurring product. Remove the trial or make it recurring.
`MEDIA_LIMIT_EXCEEDED`	400	A product supports at most 5 media items. Remove some before adding more.
`METADATA_LIMIT_EXCEEDED`	400	`metadata` allows at most 20 keys, each key and value at most 500 characters. Trim it.
`ENVIRONMENT_MISMATCH`	400	All products in a group must be in the same environment. Use one environment.
`INVALID_PRODUCT_REFERENCE`	400	A product ID is invalid or belongs to another merchant. Verify the IDs.
`INVALID_UPLOAD_REFERENCE`	400	An upload ID is invalid or belongs to another merchant. Verify the IDs.

Checkout Sessions

Encountered when creating or processing checkout sessions.

Code	Status	Cause and resolution
`CHECKOUT_ERROR`	400	A general checkout configuration or processing error. Read `detail` for the cause.
`CHECKOUT_PRICE_CHANGED`	409	The price changed after the quote was issued. Fetch a fresh quote and retry.
`CUSTOM_AMOUNT_REQUIRED`	400	A `CUSTOM`-priced product needs an `amount` in the line item. Provide one.
`FIXED_AMOUNT_OVERRIDE_NOT_ALLOWED`	400	An `amount` was set for a `FIXED`-priced product. Remove `amount` from the line item.
`HETEROGENEOUS_PRICE_TYPES`	422	All prices for a product must share one type (`FIXED`, `CUSTOM`, or `FREE`).
`PAYMENT_METHOD_NOT_ALLOWED`	400	The checkout was restricted to other payment methods or currencies. Choose one the checkout offers.
`CHECKOUT_HAS_NO_PAYMENT_METHOD`	400	Nothing can be offered on this checkout, so it was refused instead of created unpayable. Work through Why a checkout has no payment method.
`CHECKOUT_RESTRICTION_LEAVES_NO_PAYMENT_METHOD`	400	Your `payment_method_types` narrowed the checkout to nothing that is available. Widen it, or see Why a checkout has no payment method.
`ACCOUNT_NOT_ACTIVATED`	400	The account has payment methods configured but is not yet approved to accept live payments. Finish going live, or keep building against a sandbox key.
`ACCOUNT_PAYMENT_METHODS_RESTRICTED`	400	Every payment method on the account is restricted, so no checkout can offer one. You cannot lift this from your own settings. Contact support@bachs.io.
`CART_CURRENCY_MISMATCH`	400	All products in a multi-item checkout must share the same base currency.
`BASE_CURRENCY_NOT_HELD_BY_ORG`	422	A recurring checkout was priced in a currency you do not hold. One-time checkouts convert and settle in any supported currency; recurring will too once renewals settle to USD, but for now price the plan in a held currency. See Charge in any currency.
`BASE_CURRENCY_NOT_COLLECTIBLE`	422	No payment method can collect the `base_currency`. Crypto asset codes are refused here: an asset code names a rail, not a price.
`BASE_CURRENCY_NOT_ENABLED`	422	The `base_currency` is collectible, but not enabled for your organization. Enable it in your checkout settings first.
`BASE_CURRENCY_NOT_CONVERTIBLE`	422	We can collect the `base_currency` but have no rate to settle it into your settlement currency, so the checkout is refused rather than created with money that could not be paid out.
`BILLING_CURRENCY_NOT_AVAILABLE`	400	Nothing in the checkout is priced in the requested `billing_currency`. Add a price in that currency, or request one of the currencies named in `detail`.
`BILLING_CURRENCY_HAS_NO_PAYMENT_METHOD`	400	The checkout is priced in the requested `billing_currency`, but no payment method it offers can charge it. Request one of the currencies named in `detail`. See Pin the currency.

Subscriptions Limited Access

Encountered when creating or managing subscriptions.

Code	Status	Cause and resolution
`SUBSCRIPTIONS_NOT_ENABLED`	403	Subscriptions are not enabled for this account. Contact support to request access.
`NGN_SUBSCRIPTIONS_NOT_ENABLED`	403	NGN subscriptions are not enabled. Contact support to request access.
`TRIALS_NOT_ENABLED`	403	Trials are not enabled for this account. Contact support to request access.
`SUBSCRIPTION_NOT_FOUND`	404	No subscription exists for this ID in your scope. Verify the ID.
`SUBSCRIPTION_ALREADY_CANCELED`	400	The subscription is already canceled and cannot be canceled again.
`SUBSCRIPTION_NOT_MODIFIABLE`	400	The subscription cannot be modified in its current status. Check its status first.
`SUBSCRIPTION_NOT_TRIALING`	400	The action requires a trialing subscription, but this one is not in a trial.
`INVALID_SUBSCRIPTION_PRICE`	400	The price is not valid for a subscription. It must be recurring with a positive amount.
`SUBSCRIPTION_PRICE_NOT_RECURRING`	400	A subscription needs a recurring price. Use a product with one.
`SUBSCRIPTION_REQUIRES_CATALOG_PRODUCT`	400	A subscription checkout needs exactly one recurring catalog product. Raw amounts and inline products are not supported.
`SUBSCRIPTION_METHOD_NOT_SUPPORTED`	400	Subscription checkouts can only be paid with a card. Use a card.
`PLAN_NOT_PRICED_IN_CURRENCY`	400	The target product has no price in the subscription’s currency. Add one or choose another plan.
`SUBSCRIPTION_PLAN_INTERVAL_MISMATCH`	400	The target product’s interval must match the subscription’s. Choose a matching plan.
`PRORATION_BEHAVIOR_NOT_SUPPORTED`	400	The requested proration behavior is not supported yet. Use a supported value.

Payouts

Encountered when sending payouts or managing payout destinations.

Code	Status	Cause and resolution
`PAYOUTS_NOT_ENABLED`	400	Withdrawals are not enabled for this organization. Complete the account’s withdrawal requirements; contact support if the error persists.
`PAYOUT_CURRENCY_NOT_ENABLED`	400	The requested payout route is disabled for this account. Global payouts are available to all Bachs users; if this occurs for a supported route, contact support with the error details.
`PAYOUT_SOURCE_CURRENCY_UNSUPPORTED`	400	The chosen source balance cannot fund this route. International bank and mobile money payouts use your USD balance.
`PAYOUT_RECIPIENT_INCOMPLETE`	400	Required account identity details are missing. Complete the account’s name, contact email and address before requesting the payout.
`DESTINATION_NOT_FOUND`	404	No destination with that id belongs to this account. Check the id.
`DESTINATION_PENDING_REVIEW`	400	The destination has not cleared review, so it cannot receive money yet. Wait for `is_usable` to be `true`.
`DESTINATION_REJECTED`	400	The destination was rejected in review and never becomes usable. Register a new one.
`DESTINATION_TYPE_REQUIRED`	400	The currency is served by more than one payout rail, so the type cannot be inferred. Send `type` explicitly.
`CURRENCY_NOT_SUPPORTED`	400	The requested payout currency and destination type have no supported rail. See Supported currencies.
`AMOUNT_REQUIRED`	400	A same-currency payout needs an `amount`.
`AMOUNT_NOT_ALLOWED_WITH_QUOTE`	400	A quoted payout carries no `amount`, because the quote already fixes both sides. Send one or the other.
`QUOTE_REQUIRED`	400	The destination’s currency differs from the balance being debited. Create a quote and pass `quote_id`.
`QUOTE_NOT_APPLICABLE`	400	A quote was passed to a same-currency payout, which converts nothing. Drop `quote_id`.
`QUOTE_NOT_FOUND`	400	The quote does not exist, or belongs to another organization. Create a new one.
`QUOTE_EXPIRED`	400	The quote has lapsed. Quotes are short-lived; create one immediately before the payout.
`QUOTE_DESTINATION_MISMATCH`	400	The quote was created for a different currency pair than this destination’s. Quote the pair you are paying.
`PAYOUT_DESTINATION_NOT_FOUND`	404	No destination with that id belongs to this account. Returned when choosing the destination a payout schedule uses.
`PAYOUT_DESTINATION_NOT_APPROVED`	400	Only an approved destination can be a payout schedule’s default. Wait for review to clear.
`PAYOUT_DESTINATION_INACTIVE`	400	A deleted destination cannot be a payout schedule’s default. Register the account again and promote the new one.
`WITHDRAWAL_LIMIT_EXCEEDED`	400	The amount exceeds your single-withdrawal limit. `details` has `currency`, `requested_amount` and `max_allowed`, plus `requested_amount_usd` and `max_allowed_usd`. See Withdrawal limit details. Lower the amount.
`DAILY_WITHDRAWAL_LIMIT_EXCEEDED`	400	The amount would exceed your daily cap. `details` has `currency`, `requested_amount`, `max_allowed` and `total_today`, plus `requested_amount_usd`, `max_allowed_usd` and `total_today_usd`. See Withdrawal limit details. Retry within the cap.
`INSUFFICIENT_BALANCE`	400	`available_balance` will not cover the payout. Compare it against `total_debited` (what the destination receives plus the fee), not against `amount`. See General for the shortfall the response states.

Limit errors include a details object alongside error_code and detail. Parse it to show remaining allowance and cap amounts directly to your users.

Withdrawal limit details

currency, requested_amount, max_allowed and total_today are in the currency the limit is set in. total_today is only on the daily error. If your account has a limit for the payout currency, the payout is judged against that limit only. The amounts are in that currency, and the _usd fields are null. If it has no limit for that currency, the check is in USD. currency is "USD", and the _usd fields are filled. For example, an NGN payout of 12,000,000 against a 10,000,000 limit:

{
  "detail": "Withdrawal limit exceeded. Requested: NGN 12,000,000.00, maximum allowed: NGN 10,000,000.00",
  "error_code": "WITHDRAWAL_LIMIT_EXCEEDED",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#payouts",
  "details": {
    "requested_amount_usd": null,
    "max_allowed_usd": null,
    "currency": "NGN",
    "requested_amount": "12000000.00",
    "max_allowed": "10000000.00"
  }
}

Deposits

Encountered when collecting payments from customers.

Code	Status	Cause and resolution
`DEPOSIT_LIMIT_EXCEEDED`	400	The payment exceeds your deposit limit for this currency. `details` has `requested_amount`, `max_allowed_amount`, and `currency`. Lower the amount or contact support.
`UNSUPPORTED_DEPOSIT_CURRENCY`	400	The currency is not a supported deposit currency. Use a supported currency.

Virtual accounts

Encountered when creating or reading an account’s fixed account number. See Virtual accounts.

Code	Status	Cause and resolution
`VIRTUAL_ACCOUNT_CURRENCY_NOT_SUPPORTED`	400	We do not issue virtual accounts in that currency. Request `NGN`, the only supported currency today.
`VIRTUAL_ACCOUNT_REFUSED`	400	The issuing bank refused to create the number. The message carries the bank’s reason. Fix what it names and retry, or contact support if it isn’t clear.
`FORBIDDEN`	403	Your key lacks `virtual_accounts:read` or `virtual_accounts:write`, or the account’s `virtual_accounts` capability is not active yet. Check the key’s permissions, then wait for `capability.updated` to report the capability as `active`.
`VALIDATION_FAILED`	422	The account representative has no BVN on file. The response includes `missing_fields: ["bvn"]`. Submit the representative’s BVN through the account’s requirements, then retry.
`NOT_FOUND`	404	On `GET`, the account has no virtual account in that currency, so create one with `POST /v1/virtual-accounts`. On `POST`, virtual accounts are not enabled for this account yet. They are rolling out account by account, and each connected account is enabled separately. Contact support with the account ID.

Quotes Limited Access

Encountered when requesting conversion quotes.

Code	Status	Cause and resolution
`QUOTE_ERROR`	400	The conversion quote could not be generated. Check the currency pair and amount are valid.

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Media

Misc

Transfers

Persons

Platform Fees

Reference

Error Reference

General

Payments

Products & Prices

Checkout Sessions

Subscriptions Limited Access

Payouts

Withdrawal limit details

Deposits

Virtual accounts

Quotes Limited Access

​General

​Payments

​Products & Prices

​Checkout Sessions

​Subscriptions Limited Access

​Payouts

​Withdrawal limit details

​Deposits

​Virtual accounts

​Quotes Limited Access

General

Payments

Products & Prices

Checkout Sessions

Subscriptions Limited Access

Payouts

Withdrawal limit details

Deposits

Virtual accounts

Quotes Limited Access