> ## Documentation Index > Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt > Use this file to discover all available pages before exploring further. # 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`](https://docs.brale.xyz/webhooks/webhook-events#transfer-completed) and [`transfer.failed`](https://docs.brale.xyz/webhooks/webhook-events#transfer-failed) [webhooks](https://docs.brale.xyz/webhooks/overview.md) and use polling as a fallback or reconciliation mechanism. See [webhook troubleshooting](https://docs.brale.xyz/webhooks/troubleshooting.md) for delivery diagnostics. ## Headers * Required: `Authorization: Bearer `, `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](https://docs.brale.xyz/guides/individual-accounts.md) and [Account types](https://docs.brale.xyz/key-concepts/account-types.md) 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](https://docs.brale.xyz/key-concepts/account-types.md). ### 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](https://docs.brale.xyz/coverage/account-availability.md) 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](https://docs.brale.xyz/key-concepts/accounts.md#creating-a-regulated-non-us-custodial-business-account). ### 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](https://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 > [!TIP] > > **Subscribe before you go live.** Click **Subscribe to updates** on [status.brale.xyz](https://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.