Erros

Todos os erros trazem error (código estável, use no seu código) e message (texto para pessoas). Para o formato geral e rate limit, ver Erros e rate limit.

{ "error": "insufficient_balance", "message": "Saldo USDC insuficiente", "statusCode": 422 }

Todas as recusas de saque (4xx) acontecem antes de reservar saldo ou de criar qualquer coisa no provedor: é seguro corrigir e tentar de novo com uma Idempotency-Key nova.

HTTP	error	Quando	O que fazer
400	(validação)	Campo ausente, inválido ou desconhecido.	Corrija o corpo.
400	idempotency_key_required	Saque sem Idempotency-Key válido.	Envie o header (8 a 160 caracteres A-Z a-z 0-9 _ -).
400	invalid_pix_key	Chave Pix não bate com o tipo.	Confira pixKey e pixKeyType.
401	Unauthorized	Chave de API ausente ou inválida.	Confira o X-Api-Key.
403	crypto_disabled	Cripto não liberado para a loja.	Peça a liberação à Gestão Intermediações.
403	kyc_required	Cliente ainda não aprovado (traz status; no depósito, os links se a sua loja iniciou o KYC).	Reenvie os links e aguarde o webhook crypto.customer.updated.
404	customer_not_found / deposit_intent_not_found / payout_not_found / withdrawal_not_found	Id ou referência não existe na sua loja.	Confira o id.
409	merchant_not_ready	A empresa não está ativa na Gestão Intermediações.	Fale com o suporte.
409	merchant_wallet_not_ready	Saque do saldo da loja sem o cadastro cripto da loja aprovado. Traz status, kycLink, tosLink.	Conclua o cadastro cripto da loja no painel.
409	identity_mismatch	externalRef já usada com outro CPF, ou documento com cadastro de empresa.	Confira o CPF.
409	idempotency_conflict	Mesma Idempotency-Key com corpo diferente.	Use uma chave nova para um saque novo.
422	insufficient_balance	Saldo disponível menor que o valor do saque.	Consulte /crypto/balance.
422	limit_exceeded	Acima do limite por saque ou do limite diário da loja.	Divida o valor ou peça ajuste do limite.
422	amount_below_minimum	O valor que chegaria no Pix (valor − taxa) fica abaixo de R$ 10,00.	Aumente o valor.
422	WITHDRAW_FEE_EXCEEDS_AMOUNT	A taxa consome todo o valor do saque.	Aumente o valor.
422	provider_cost_exceeds_fee	A taxa configurada para a loja não cobre o custo do provedor nesse saque.	Fale com a Gestão Intermediações para revisar a taxa.
422	pix_key_not_owned	Saque da loja: o provedor não aceitou a chave para o titular informado (CPF/CNPJ sem chave Pix ativa, ou chave e-mail/telefone/aleatória de outra pessoa sem o recipientDocument certo). A mensagem não diz se falhou a chave ou o documento.	Confira a chave e, se ela for de outra pessoa, o recipientDocument.
429	Too many requests	Mais de 30 pedidos por minuto em POST /crypto/withdrawals ou POST /crypto/payouts.	Espere retryAfterSeconds e repita com a mesma Idempotency-Key.
422	refund_under_review	Há depósito do cliente devolvido em análise.	Aguarde a análise do suporte.
422	company_document_invalid	Empresa sem CPF/CNPJ válido cadastrado (saque da loja).	Fale com o suporte.
409	provider_conflict	Conflito no provedor cripto (traz code).	Releia o item antes de repetir; não repita às cegas.
409	provider_reconciliation_required	A operação ficou pendente no provedor e precisa ser reconciliada pelo suporte.	Fale com o suporte. Não repita com outros dados (outro nome ou e-mail): a nova tentativa também é recusada.
422	provider_rejected	O provedor cripto recusou a operação. Traz code e, quando o provedor informa, reason (motivo) e fields (campos recusados, ex.: ["email"]).	Corrija o campo indicado; se persistir, fale com o suporte informando code e reason.
503	provider_unavailable	Cotação ou provedor indisponível no momento.	Tente de novo em instantes, com a mesma Idempotency-Key.
503	crypto_unavailable	Módulo cripto temporariamente indisponível.	Tente de novo mais tarde.