Skip to main content

Troubleshooting & Known Pitfalls

Use this checklist when integrating and operating at volume.

Auth & tokens

  • Tokens expire in ~60 minutes; refresh using expires_in before expiry.
  • 401 → refresh token, retry idempotently. Do not keep reusing an expired token.

Environments & identifiers

  • Single account context: your account_id is the same on testnet and mainnet.
  • Environment-scoped clients: an API client is either testnet or mainnet, never both.
  • Use the correct client when minting the access token; a testnet client used on mainnet (or vice versa) will fail.

Idempotency

  • Required on POST create endpoints (e.g., transfers). Missing key → 400.
  • Never reuse an Idempotency-Key with a different payload or URI (422).
  • Do not send Idempotency-Key on GETs.
  • Best practice: generate one UUID per logical action and persist it so retries reuse the same key.

IDs (account_id vs address_id)

  • IDs are KSUIDs (27-char, time-sortable), not UUIDs—copy/paste carefully.
  • address_id is the universal source/destination primitive (wallets and fiat endpoints).
  • Internal (custodial) addresses are auto-created per account/chain; generally you do not create them manually.
  • If an address appears under an account-scoped endpoint but not via a global lookup, use the account-scoped endpoint.

Transfers: value_type + transfer_type

  • Source and destination are always address-based; both carry value_type and transfer_type.
  • Use valid pairs from Coverage (value types and transfer types are case-sensitive).
  • Branding applies to ACH, outbound wire payouts, and FedNow payouts. See Branded Transfers.

Pagination & reconciliation

  • List transfers with pagination tokens; store transfer id, idempotency key, timestamps, status, and provider references.
  • Poll with backoff; avoid tight loops.
  • If you are waiting for transfer completion in production, consider using transfer.completed and transfer.failed webhooks and use polling as a fallback or reconciliation mechanism. See webhook troubleshooting for delivery diagnostics.

Headers

  • Required: Authorization: Bearer <token>, Content-Type: application/json on JSON POSTs, Idempotency-Key on create POSTs.
  • Avoid sending unexpected headers (including Idempotency-Key) on GET.

Common errors

403 network_not_supported

  • Usually caused by using a testnet-scoped API client for a mainnet request, or a mainnet client for testnet.
  • Fix: use an API client created for the target environment and mint a new access token.

400 invalid_transfer_types on address creation

  • Response detail: Invalid transfer types; Address transfer types must be compatible chains.
  • Common cause: transfer_types on POST /accounts/{account_id}/addresses/external includes rtp_credit. RTP ended on October 30, 2026. The error mentions chains, but the rejected value is rtp_credit.
  • Fix: replace rtp_credit with fednow_credit. See Migrate from rtp_credit to fednow_credit.
  • If the request does not include rtp_credit and fednow_credit is rejected, contact [email protected] to confirm FedNow is enabled on your account.

400 invalid_transfer_type on transfer creation

  • Response detail: Invalid transfer type.
  • Common cause: destination.transfer_type on POST /accounts/{account_id}/transfers is rtp_credit.
  • Fix: confirm the destination bank Address lists fednow_credit in transfer_types, then set destination.transfer_type to fednow_credit. Brale did not create a Transfer for the rejected request. See Migrate from rtp_credit to fednow_credit.

404 compatible_address_not_found

  • Causes:
    • address is not compatible with the requested transfer_type in that environment
    • typo in address_id
    • address_id does not belong to the specified account_id on an account-scoped route
  • Fix: verify the address_id belongs to the account_id, ensure the address supports the transfer_type, and double-check casing.

422 compatible_address_not_found (transactional accounts)

  • Cause: the source account is a transactional account. Transactional accounts cannot originate on-chain transfers — their external addresses are destination-only, and they hold no internal (custodial) addresses. Checking the address balance first does not predict this; the constraint is about the address role, not funds.
  • Fix: route outbound value through a custodial account. See Individual accounts and Account types for what a transactional account can and cannot do.

400 redemption_limit_exceeded on testnet USDC transfers

  • Cause: Brale caps testnet transfers that involve USDC, including SBC↔USDC swaps, at $0.01 per transfer because of testnet faucet limits.
  • Open testnet USDC transfers created before the cap took effect may show status: "canceled".
  • Fix: keep testnet USDC transfers at $0.01 or less. The cap does not apply on mainnet, where limits depend on your plan. See Testnet limitations and Transfer limits.

Simulated deposit has no source.payment_details

  • Cause: simulated Automation deposits carry no sender or bank data, so Brale does not populate source.payment_details. Brale does not add it later in GET responses or webhooks.
  • Fix: treat payment_details as optional and possibly null. See Testnet limitations.

422 insufficient_balance when the address shows enough funds

  • Cause: Brale checks the source address’s available balance, not its onchain total. Brale subtracts transfers from that address that are still pending or processing. A block explorer, or Get an address balance, can show more than you can spend while those transfers are in flight.
  • This is common when you send several transfers from the same address in quick succession, for example a conversion followed by a burn.
  • Fix: wait for the in-flight transfers to reach a terminal status, then retry with the same Idempotency-Key and body. You can also lower the amount. Lowering the amount changes the request, so use a new key.
  • Track in-flight amounts on your side. Before you create a transfer, subtract your own pending and processing transfers from the same source address from the balance you read.

422 on transfers to a bank address that received a return

  • Cause: when a bank returns a payment to an external bank address, for example an ACH return, Brale can disable that address. New transfers to a disabled address fail with 422.
  • Check the transfer.failed webhook or the transfer’s failure field for the return code and reason.
  • Fix: confirm with the recipient that the bank account can receive payments. Then contact Brale support to re-enable the address. After Brale re-enables it, retry the transfer.

422 external_address_disabled

  • Cause: you tried to register a bank account that matches an external address Brale disabled after a return. Registering the same bank account again does not create a new, usable address.
  • Fix: contact Brale support to re-enable the existing address. After Brale re-enables it, use the existing address_id. To add rails such as fednow_credit or wire, use Update an Address with additional_transfer_types.

422 unsupported_account_combination

  • Causes:
    • verification_mode: bypass, which is not supported for any combination
    • verification_mode: reliance from a caller without reliance enabled — reliance is enabled per managing account by Brale and is not self-serve
  • All eight combinations of entity_type (business, individual), account_type (custodial, transactional), and verification_mode (standard, reliance) are supported.
  • The rejection is permanent, so it is safe to cache this error against your idempotency key.
  • Fix: adjust the dimension fields to a supported combination. See Account types.

422 unsupported_jurisdiction

  • Cause: Brale does not serve the applicant’s jurisdiction for the requested account type. Individual custodial accounts are U.S.-only and per-state. Business custodial accounts are per-state in the U.S.; outside the U.S. they are refused unless the business sends a regulatory_profile and is in an approved country. Transactional accounts are unavailable in some U.S. states and outside the approved country list.
  • The rejection is permanent, so it is safe to cache this error against your idempotency key.
  • Fix: check Account availability for where each customer and account type combination is available.

400 regulator_required

  • Cause: a business request sent regulatory_profile with regulator missing or blank.
  • The rejection is permanent, so it is safe to cache this error against your idempotency key.
  • Fix: set regulatory_profile.regulator to the authority the business is licensed or registered with, for example FINTRAC. If the business is not regulated, omit regulatory_profile entirely. See Accounts.

400 license_number_required

  • Cause: a business request sent regulatory_profile with license_number missing or blank.
  • The rejection is permanent, so it is safe to cache this error against your idempotency key.
  • Fix: set regulatory_profile.license_number to the license or registration number the regulator issued. If the business is not regulated, omit regulatory_profile entirely.

422 invalid_us_state

  • Cause: the individual’s country is US and address.state is missing, blank, or not a recognized US state or territory. Abbreviations and full names are both accepted (CA, California, PR).
  • A US territory is a US jurisdiction, not a separate country: send country: "US" with the territory in address.state (PR, GU, AS, VI, MP).
  • Fix: send a valid US state or territory in address.state. For a non-US individual, address.state is optional and free-form.

Platform status

Brale publishes real-time updates on incidents and scheduled maintenance at status.brale.xyz. Status is reported per transfer type and chain, for example Wire, ACH, Solana, and EVM, so you can see whether an issue affects your integration. What Brale publishes:
  • Incidents affecting the API, transaction processing, or specific transfer types
  • Scheduled maintenance, announced in advance
  • Updates as an incident progresses, and a notice when it’s resolved
Subscribe before you go live. Click Subscribe to updates on status.brale.xyz to get notified when Brale opens, updates, or resolves an incident.

When in doubt

  • Re-read Coverage for exact identifiers (case and spelling).
  • Verify example paths and enums against the OpenAPI spec and Postman collection.