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 (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. Custodial accounts (business and individual) are U.S.-only and per-state; 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.

​
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.

​
When in doubt

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