Catálogo de erros

Referência alfabética para cada código de erro que a BlendFi pode retornar, status, quem causou, o que fazer.

Todo erro da BlendFi tem um code estável no qual você pode bifurcar, um status HTTP que dá pista de semântica de retentativa e um request_id curto que você cola ao pedir suporte. Esta página é a lista alfabética canônica. Para o porquê do contrato, veja Erros e retentativas.

Como ler esta página

Cada entrada mostra:

Status: o status HTTP que a BlendFi retorna junto com o code
Causado por: partner (algo a corrigir no seu código), user (algo para o usuário final corrigir), BlendFi (infra transitória) ou upstream (verificação de identidade / provedor Pix / provedor de custódia / uma exchange regulada)
Retentar?: ✅ seguro retentar (com a Idempotency-Key original), ❌ não retente, ⚠️ condicional
Recuperação: o que o seu código ou o usuário deve fazer

Códigos terminando em _unavailable são sempre transitórios e seguros para retentar. Códigos começando com invalid_ ou duplicate_ são erros de input do parceiro, corrija o input e resubmita.

Os códigos não traduzem

As strings de code são identificadores estáveis e permanecem em inglês em todas as respostas. Apenas message (humano) e a prosa neste catálogo são traduzidas.

Code	Status	Causado por	Retentar?	Ação
amount_mismatch	422	Usuário(offramp)	Não	O valor depositado em USDT não bateu com o valor cotado (até o último wei). A transação está `failed`. Recuperação: o usuário deposita o valor correto via uma cotação nova, esta transação é terminal.
api_key_env_mismatch	401	Parceiro	Não	Você usou uma chave `sk_live_…` no sandbox ou uma chave `sk_test_…` em produção. Confira de novo a sua configuração de ambiente.
authentication_failed	401	Parceiro	Não	API key desconhecida, revogada ou expirada, ou a sua organização está suspensa. Copie a chave de novo a partir do email de onboarding; se não funcionar, entre em contato com o suporte com o `request_id`.
authentication_required	401	Parceiro	Não	Header `Authorization` ausente ou que não começa com `Bearer` . Atenção ao espaço após `Bearer`.
crypto_kyc_declined	422	Usuário	Não	O KYC de tier cripto do usuário foi recusado. Ele não pode transacionar cripto. Veja KYC.
crypto_kyc_pending	422	Usuário	Condicional	O KYC de tier cripto do usuário ainda está em análise. Espere o webhook `user.kyc_approved` e retente.
crypto_kyc_required	422	Parceiro/ usuário	Não	O usuário precisa completar o KYC de tier cripto antes de transacionar. Dispare o fluxo de tier maior.
custody_account_not_found	404	Parceiro	Não	Você consultou uma conta de custódia que não existe para este usuário. Confira de novo o ID do usuário.
deposit_past_expiry	422	Usuário(offramp)	Não	O depósito offramp chegou on-chain depois da janela de expiração da cotação. Recuperação operacional, fluxo de suporte manual.
duplicate_document	409	Parceiro	Não	Já existe um usuário com este CPF ou CNPJ na sua organização. Procure o usuário existente; não tente criar um novo.
duplicate_external_id	409	Parceiro	Não	`external_id` já em uso na sua organização. Escolha um valor único.
idempotency_key_in_progress	409	Parceiro	Condicional	Um request idêntico ainda está sendo processado. Faça backoff curto (100–500 ms) e retente a mesma chamada. Veja Idempotência.
idempotency_key_required	400	Parceiro	Não	Header `Idempotency-Key` ausente em request mutante. Adicione o header.
idempotency_key_reused	409	Parceiro	Não	A mesma `Idempotency-Key` foi usada antes com um body diferente. Ou reenvie o body original para replay, ou use uma chave nova para o body novo.
invalid_amount	422	Parceiro	Não	O valor deve ser decimal positivo. Valide antes de submeter.
invalid_amount_precision	422	Parceiro	Não	O valor tem casas decimais demais para a moeda. BRL permite 2; USDT permite até a precisão definida no token.
invalid_capability	400	Parceiro	Não	Capability desconhecida solicitada. (Erro do lado admin; parceiros normalmente não veem isso.)
invalid_cnpj	422	Usuário	Não	Formato ou dígitos verificadores do CNPJ inválidos. 14 dígitos, sem pontos, barras ou traços.
invalid_cpf	422	Usuário	Não	Formato ou dígitos verificadores do CPF inválidos. 11 dígitos, sem pontos ou traços.
invalid_custody_account_state	422	Usuário/ BlendFi	Condicional	Operação não permitida no estado atual da conta de custódia do usuário. Pode se resolver quando o provisionamento concluir.
invalid_cursor	400	Parceiro	Não	Cursor mal formado em endpoint de listagem. Descarte e comece do início.
invalid_kyc_state	422	Usuário	Não	Operação não permitida no estado de KYC atual do usuário. Veja KYC.
invalid_kyc_submission_state	422	Usuário	Não	O estado da submissão de KYC não permite esta operação.
invalid_offramp_quote	422	Parceiro	Não	A cotação não é de offramp. Use uma cotação com `transaction_type: pix_offramp`.
invalid_organization_state	422	BlendFi	Não	A organização está suspensa ou bloqueada. Entre em contato com o suporte.
invalid_pix_key_format	422	Usuário	Não	Formato da chave Pix não bate com o tipo declarado. Valide antes de submeter. Veja Pix.
invalid_transaction_state	409	Parceiro/ estado	Não	Operação não permitida no estado atual da transação. Leia a transação; reconcilie o seu estado local.
invalid_user_wallet_state	422	BlendFi	Condicional	O estado da wallet do usuário não permite esta operação. Pode se resolver quando o provisionamento concluir.
invalid_wallet_address	422	Parceiro	Não	O endereço de wallet não é válido para a rede declarada. Endereços Polygon estão no formato EVM (`0x` + 40 chars hex).
invalid_webhook_delivery_state	422	Parceiro	Não	A entrega de webhook não está em um estado que permita a operação (ex.: reentrega de uma que já está em andamento).
invalid_webhook_endpoint_state	422	Parceiro	Não	O endpoint de webhook não está em um estado que permita a operação.
invalid_webhook_event_types	400	Parceiro	Não	O array `event_types` está vazio ou contém um tipo desconhecido. Veja o catálogo de eventos para a lista completa de nomes válidos de evento.
invalid_webhook_signature	401	Parceiro	Não	A assinatura de webhook não bateu. Confira de novo os quatro erros canônicos, veja Webhooks.
invalid_webhook_url	400	Parceiro	Não	A URL de webhook precisa ser HTTPS. HTTP puro e outros schemes são rejeitados.
kyb_not_yet_supported	422	Parceiro	Não	KYC empresarial não é suportado na v1. Usuários CNPJ ainda passam pelo fluxo de pessoa física por enquanto.
kyc_already_approved	409	Parceiro	Não	A submissão de KYC já está aprovada. Sem necessidade de submeter de novo.
kyc_provider_unavailable	502	Upstream(verificação de identidade)	Sim	verificação de identidade está temporariamente indisponível. Retente com a mesma `Idempotency-Key`.
kyc_required	422	Usuário	Não	O usuário precisa completar o KYC antes desta operação. Dispare o fluxo de verificação.
kyc_submission_not_found	404	Parceiro	Não	O ID da submissão de KYC não existe para este usuário.
max_webhook_endpoints_reached	422	Parceiro	Não	A organização está no limite de endpoints de webhook. Apague um que não esteja em uso ou entre em contato com o suporte.
missing_capability	403	Parceiro	Não	API key sem a capability necessária para este endpoint. Envie um email ao suporte para ampliar as capabilities da chave.
open_conversion_exists	409	Parceiro/ user	Não	Apenas uma conversão aberta é permitida por usuário por direção. Cancele ou expire a existente antes de criar outra, ou reaproveite a conversão já aberta.
organization_not_found	404	BlendFi	Não	Falha de consulta interna. Entre em contato com o suporte com o `request_id`.
pix_key_not_found	404	Usuário	Não	O DICT não reconhece a chave Pix fornecida. O usuário digitou errado ou não cadastrou a chave no banco.
pix_key_ownership_mismatch	422	Usuário	Não	O titular registrado no DICT não bate com o documento armazenado do usuário. Ou o usuário está errado, ou a chave está errada, ou foi pego pela validação dupla.
pix_provider_unavailable	502	Upstream(provedor Pix)	Sim	Provedor Pix está temporariamente indisponível. Retente com a mesma `Idempotency-Key`.
pix_send_failed	502	Upstream(provedor Pix)	Condicional	Provedor Pix rejeitou o pagamento Pix. A transação está `failed`. A recuperação é manual, entre em contato com o suporte.
price_feed_unavailable	502	Upstream	Sim	O feed de preços que a BlendFi usa para cálculo de cotação está temporariamente indisponível. Retente em breve.
quote_already_consumed	409	Parceiro	Não	A cotação já foi usada para criar uma transação. Pegue uma cotação nova.
quote_expired	409	Parceiro	Não	A cotação passou de `expires_at` (geralmente 30 s). Pegue uma cotação nova.
quote_not_found	404	Parceiro	Não	O ID da cotação não existe ou não está no escopo do seu tenant.
rate_limit_exceeded	429	Parceiro	Sim	Diminua o ritmo. Espere `details.retry_after_seconds` (também no header `Retry-After`) antes de retentar. Veja Ambientes e limites.
internal_error	500	BlendFi	Sim	Erro inesperado no servidor. Retente com a mesma `Idempotency-Key`. Se persistir, entre em contato com o suporte com o `request_id`.
transaction_limit_exceeded	422	Parceiro/ usuário	Não	A transação excederia o limite do usuário ou da organização. Reduza o valor ou entre em contato com o suporte para aumentar os limites.
transaction_not_found	404	Parceiro	Não	O ID de transação não existe ou não está no escopo do seu tenant.
transaction_settlement_not_found	404	BlendFi	Não	Registro interno de liquidação ausente. Entre em contato com o suporte.
unsupported_currency	422	Parceiro	Não	Moeda fora do conjunto suportado. A v1 suporta apenas BRL e USDT.
unsupported_deposit_network	422	Parceiro	Não	Rede de depósito não suportada. A v1 suporta Polygon (Ethereum e Solana em breve).
unsupported_withdraw_network	422	Parceiro	Não	Rede de saque não suportada. A v1 suporta Polygon (Ethereum e Solana em breve).
user_kyc_not_approved	422	Usuário	Não	O KYC do usuário não está aprovado. Mesma família de `kyc_required`.
user_missing_enrollment_data	422	Parceiro	Não	Usuário sem os dados necessários para enrollment no provedor de wallet. Faça PATCH no usuário com os campos faltantes.
user_not_found	404	Parceiro	Não	O ID de usuário não existe ou não está no escopo do seu tenant.
user_wallet_not_found	404	Parceiro	Não	O ID de wallet não existe para este usuário.
validation_error	400	Parceiro	Não	O body do request não bate com o schema. `details.issues[]` lista os caminhos específicos dos campos.
wallet_provider_enrollment_rejected	422	Upstream(provedor de custódia)	Não	A provedor de custódia rejeitou o enrollment do usuário. Operacional; entre em contato com o suporte.
wallet_provider_unavailable	503	Upstream(provedor de custódia)	Sim	provedor de custódia está temporariamente indisponível. Retente com a mesma `Idempotency-Key`.
wallet_provisioning_unavailable	503	Upstream(provedor de custódia)	Sim	O provisionamento de wallet do usuário está temporariamente indisponível. Retente com a mesma `Idempotency-Key`.
webhook_delivery_not_found	404	Parceiro	Não	O ID de entrega de webhook não existe.
webhook_endpoint_not_found	404	Parceiro	Não	O ID de endpoint de webhook não existe.
withdraw_provider_unavailable	502	Upstream	Sim	O provedor de saque está temporariamente indisponível. Retente em breve.

Relacionado

Erros e retentativas (Conceitos), o porquê do contrato
Idempotência (Conceitos), por que retentar com a mesma chave é seguro
Glossário, definições para request_id, verificação de identidade, provedor Pix, provedor de custódia

Como ler esta página

Relacionado

Nesta página