> ## 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`](/webhooks/webhook-events) [webhooks](/webhooks/overview) and use polling as a fallback or reconciliation mechanism. See [webhook troubleshooting](/webhooks/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.

## When in doubt

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