Troubleshooting & Known Pitfalls

Common issues, quick fixes, and how to avoid retries gone wrong.

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 (26-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 only (not wire/RTP).

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.

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.

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.