Errors catalog

The deposited USDT amount didn't match the quoted amount (down to the wei). The transaction is failed. Recovery: the user re-deposits the correct amount via a fresh quote, this transaction is terminal.

You used a sk_live_… key in sandbox or a sk_test_… key in production. Re-check your environment configuration.

API key is unknown, revoked, expired, or your organization is suspended. Re-copy the key from your onboarding email; if that doesn't work, contact support with the request_id.

Authorization header missing or doesn't start with Bearer . Mind the space after Bearer.

User's crypto-tier KYC was declined. They cannot transact crypto. See KYC.

User's crypto-tier KYC is still under review. Wait for the user.kyc_approved webhook, then retry.

User must complete crypto-tier KYC before transacting. Trigger the higher-tier flow.

Asked about a custody account that doesn't exist for this user. Re-check the user ID.

Offramp deposit landed on-chain after the quote's expiry window. Operational recovery, manual support flow.

A user with this CPF/CNPJ already exists in your organization. Look up the existing user; don't try to create a new one.

external_id already in use within your organization. Pick a unique one.

Identical request still being processed. Backoff briefly (100–500 ms) and retry the same call. See Idempotency.

Idempotency-Key header missing on a mutating request. Add the header.

Same Idempotency-Key previously used with a different body. Either resend the original body to replay, or use a new key for the new body.

Amount must be a positive decimal. Validate before submitting.

Amount has too many decimal places for the currency. BRL allows 2; USDT allows up to the token's defined precision.

Unknown capability requested. (Admin-side error; partners shouldn't normally see this.)

CNPJ format or check digits are invalid. 14 digits, no dots/slashes/dashes.

CPF format or check digits are invalid. 11 digits, no dots or dashes.

Operation not allowed in the user's current custody-account state. May resolve when provisioning completes.

Cursor on a list endpoint is malformed. Drop it and start from the beginning.

Operation not allowed in the user's current KYC state. See KYC.

KYC submission state doesn't allow this operation.

Quote isn't an offramp quote. Use a quote with transaction_type: pix_offramp.

Organization is suspended or otherwise blocked. Contact support.

Pix key format doesn't match its declared type. Validate before submitting. See Pix.

Operation not allowed in the transaction's current state. Read the transaction; reconcile your local state.

User wallet state doesn't allow this operation. May resolve when provisioning completes.

Wallet address isn't valid for the declared network. Polygon addresses are EVM-format (0x + 40 hex chars).

Webhook delivery isn't in a state that allows the operation (e.g., redelivering one already in flight).

Webhook endpoint isn't in a state that allows the operation.

event_types array empty or contains an unknown type. See the event catalog for the full list of valid event names.

Webhook signature didn't match. Re-check the four canonical mistakes, see Webhooks.

Webhook URL must be HTTPS. Plain HTTP and other schemes are rejected.

Business KYC isn't supported in v1. CNPJ users still go through the individual flow for now.

KYC submission already approved. No need to re-submit.

Identity verification is temporarily unavailable. Retry with the same Idempotency-Key.

User must complete KYC before this operation. Trigger the verification flow.

KYC submission ID doesn't exist for this user.

Organization at the cap on webhook endpoints. Delete an unused one or contact support.

API key lacks the required capability for this endpoint. Email support to widen the key's capabilities.

Only one open conversion is permitted per user per direction. Cancel or expire the existing one before creating another, or reuse the existing conversion.

Internal lookup failure. Contact support with the request_id.

DICT doesn't recognize the supplied Pix key. The user mistyped, or hasn't registered the key with their bank.

DICT-registered holder doesn't match the user's stored document. Either the wrong user, the wrong key, or a verify-twice catch.

Our Pix rails is temporarily unavailable. Retry with the same Idempotency-Key.

Our Pix rails rejected the Pix payout. The transaction is failed. Recovery is manual, contact support.

The price feed BlendFi uses for quote calculation is temporarily unavailable. Retry shortly.

Quote already used to create a transaction. Get a fresh quote.

Quote past its expires_at (typically 15 minutes). Get a fresh quote.

Quote ID doesn't exist or isn't in your tenant scope.

Slow down. Wait details.retry_after_seconds (also in the Retry-After header) before retrying. See Environments and rate limits.

Unexpected server error. Retry with the same Idempotency-Key. If it persists, contact support with the request_id.

Transaction would exceed the user or organization limit. Reduce the amount or contact support to raise limits.

Transaction ID doesn't exist or isn't in your tenant scope.

Internal settlement record missing. Contact support.

Currency not in the supported set. v1 supports BRL and USDT only.

Deposit network not supported. v1 supports Polygon for USDT settlement (Ethereum and Solana are planned).

Withdraw network not supported. v1 supports Polygon for USDT settlement (Ethereum and Solana are planned).

User's KYC isn't approved. Same family as kyc_required.

User is missing data required for wallet provider enrollment. Patch the user with the missing fields.

User ID doesn't exist or isn't in your tenant scope.

User wallet ID doesn't exist for this user.

Request body doesn't match the schema. details.issues[] lists the specific field paths.

BlendFi custody rejected the user enrollment. Operational; contact support.

BlendFi custody is temporarily unavailable. Retry with the same Idempotency-Key.

User wallet provisioning is temporarily unavailable. Retry with the same Idempotency-Key.

Webhook delivery ID doesn't exist.

Webhook endpoint ID doesn't exist.

Withdrawal provider temporarily unavailable. Retry shortly.