Erros

Quando algo dá errado, a resposta explica o quê:

{ "error": { "type": "invalid_request", "message": "Esse CPF ou CNPJ não é válido. Confira os números.", "param": "customer.document" } }

A message está sempre em português e diz o que fazer, então dá para mostrar direto para quem está usando o seu sistema.

Código Quer dizer
400 falta um campo ou ele está errado (veja param)
401 chave inválida ou revogada
403 essa chave ou pessoa não pode fazer isso (veja code: restricted_key, payouts_api_disabled)
404 não existe, ou é de outra empresa
409 essa cobrança já está sendo criada (mesma Idempotency-Key)
422 não conseguimos entrar na conta conectada: confira as chaves
429 muitas chamadas seguidas. Espere alguns segundos
5xx erro nosso. Tente de novo

Dica: uma cobrança recusada não é erro. Você recebe a cobrança com status: "failed", o motivo em failure_reason (para mostrar) e um código em failure_code (para o seu sistema decidir o que fazer).

Motivos (failure_code e error.code)

São os mesmos para todas as contas. A SuyPay traduz o erro de cada uma para esta lista.

Código Quer dizer O que fazer
card_declined o banco recusou o cartão pedir outro cartão ou Pix
insufficient_funds sem limite pedir outro cartão ou Pix
card_expired cartão vencido pedir outro cartão
invalid_card dados ou token do cartão não conferem gerar o token de novo
fraud_suspected barrado pela análise de risco confirmar os dados ou pedir Pix
invalid_document CPF ou CNPJ inválido corrigir o documento
missing_document / missing_email / missing_phone a conta exige esse dado enviar o dado do cliente
invalid_data a conta recusou algum campo conferir os dados do cliente
invalid_credentials as chaves da conta pararam de funcionar atualizar em Contas conectadas
account_not_enabled o recurso não está liberado na conta pedir a liberação à empresa da conta
provider_unavailable / timeout / rate_limited a conta está fora do ar ou lenta tentar de novo; a SuyPay já tenta a próxima conta
already_paid a cobrança já foi paga nada
not_refundable a conta não devolve isso pela API devolver pelo painel da conta
not_cancelable a conta não cancela isso pela API cancelar pelo painel da conta ou esperar vencer
insufficient_balance a conta não tem saldo para o saque ou a devolução conferir o saldo e o que está retido por MED
invalid_pix_key a chave Pix não confere com o tipo corrigir a chave salva
payout_blocked saques bloqueados na conta (KYC, bloqueio do provedor) resolver no painel da conta
limit_exceeded passa do limite de saque (da conta ou o limite de 24 horas da empresa) sacar menos ou ajustar o limite
missing_scope a chave da conta não tem a permissão (por exemplo, de transferência) criar uma chave com a permissão e atualizar a conta
restricted_key a sua chave SuyPay é só cobranças e a rota pede uma chave completa usar uma chave completa no seu servidor
payouts_api_disabled saques pela API estão desligados o dono liga em Saques → Segurança

Quando a SuyPay tenta a próxima conta

Erros de infraestrutura (provider_unavailable, timeout, rate_limited) e chaves quebradas (invalid_credentials) fazem a SuyPay tentar a próxima conta na hora. Erros sobre a venda (cartão recusado, documento inválido) não: outra conta recusaria pelo mesmo motivo.

Saques nunca trocam de conta nem se repetem sozinhos. Se a conta não responder, o saque fica com uncertain: true e a SuyPay consulta de novo, sem enviar outra vez. Veja Saques.