- Um status HTTP, como
400,401ou404, que diz a classe do problema. - Um objeto
error, em JSON, com umcodeestável e uma mensagem legível.
error.code para lógica no seu sistema. Use
error.message para log, suporte e debugging.
Para recusas de cobrança, consulte também os
Códigos de falha: o catálogo explica
motivos como insufficient_funds e expired_card, a mensagem segura para o
comprador e a orientação para uma nova tentativa. Nas cobranças, esses detalhes
ficam em payment_error; no Payment Intent, em last_payment_error.
Formato
Código estável para tratamento programático. Exemplo:
parameter_missing,
authentication_failed, resource_missing.Texto em inglês explicando o problema. A mensagem pode mudar para ficar mais
clara; não faça lógica usando essa string.
Campo relacionado ao erro, quando aplicável. Pode ser um campo do body, query
param ou header.
Categoria do erro. Use para separar erros de validação, autenticação,
pagamento, rate limit e erro interno.
Tipos de erro
Status HTTP
Exemplos comuns
Use esta tabela para reconhecer a causa e decidir a ação sem abrir vários blocos de exemplo:organization_blocked
Enquanto os pagamentos da organização estiverem bloqueados, novas tentativas de cobrança ou captura recebem HTTP409 em produção e em sandbox. Operações já enviadas para processamento seguem até o desfecho. As cobranças automáticas aguardam a liberação.
403 em produção e em teste
para toda chamada com uma chave emitida pela organização bloqueada, inclusive
a chave de uma plataforma cujo próprio acesso foi bloqueado. A chave de outra
plataforma, ao operar em nome de uma organização conectada bloqueada, ainda
pode consultar, inclusive executar operações de leitura via POST. Escritas
recebem 403 organization_blocked. A mesma chave volta a funcionar em até
60 segundos após a liberação.
Páginas do comprador respondem 404 organization_unavailable quando estão
indisponíveis. Mostre “Esta página não está disponível” ao comprador.
organization_not_activated
A organização precisa de um cadastro financeiro ativo para cobrar em produção. Se esse requisito estiver pendente, a API responde com HTTP409 antes de iniciar a tentativa. Retome a cobrança quando a organização puder receber pagamentos.
amount_too_large
O valor enviado excede o teto da moeda. Embrl, o teto de cadastro é 999999999 na menor unidade. Ao cobrar, vale também o teto do meio. Em boleto, o máximo é 1000000 em brl (R$ 10.000,00). Em faturas, assinaturas e checkouts, cada item e a soma de preço × quantidade respeitam o teto antes de descontos e juros calculados depois. Reduza o valor ou a quantidade; repetir o mesmo pedido não resolve.
A resposta usa HTTP 400, type: "invalid_request_error" e param com o campo inválido. Nenhum objeto financeiro é criado para esse pedido.
amount_invalid_increment
O valor deve ser um múltiplo deamount_increment na menor unidade da moeda. O erro HTTP 400 informa currency, amount_increment e o campo em param.
payment_method_not_allowed
A moeda ou as condições da compra não permitem o meio solicitado. Pix e boleto estão disponíveis embrl. A resposta informa a moeda quando o motivo é a incompatibilidade do meio.
installment_count_exceeds_maximum
Escolha uma quantidade que caiba no período e nos limites da organização e da moeda. A resposta informacurrency e, quando há parcelamento na moeda, installment_minimum_amount. Em brl, o mínimo é 700 por parcela sobre o principal.
amount_too_small
A confirmação retorna HTTP 400,type: invalid_request_error e
param: amount quando a cobrança final não cobre o mínimo. A cobrança não é
enviada ao processamento e a mesma tentativa não deve ser repetida automaticamente.
A regra usa o plano efetivo, a bandeira, as parcelas e o contexto da plataforma.
Ela é aplicada depois dos descontos e do cálculo de juros e repasse de taxas.
Os juros pagos pela organização também precisam caber no valor disponível.
minimum_amount representa o mínimo para os componentes de juros e repasse
resolvidos nesta cotação; mudar a compra exige nova prévia e confirmação.
Um item de catálogo de R$ 0,50 é válido. O mínimo se aplica à cobrança final,
inclusive em faturas e renovações. Ciclos gratuitos não geram tentativa de cobrança.
Quando houver erro persistido, esses campos também acompanham
payment_intent.last_payment_error e charge.payment_error, com categoria
invalid e advice_code: do_not_try_again. Isso não é uma recusa do banco nem
um pedido para trocar o cartão. No MCP, os mesmos campos aparecem no erro
estruturado com retryable: false.
A organização deve corrigir o valor, desconto ou configuração da venda antes
de uma nova tentativa. Para o comprador, mostre: “A transação não pôde ser
processada. Entre em contato com o vendedor.”
payment_method_not_allowed
Pix e boleto não são escolhas permitidas em checkout com trial gratuito, inclusive em sessões já existentes. A tela oferece cartão quando sua coleta for necessária;payment_method_collection: if_required permite começar sem
método quando nada é devido hoje.
Forçar Pix ou boleto na confirmação retorna HTTP 400,
type: invalid_request_error, param: payment_method e
code: payment_method_not_allowed, com mensagem explicando a restrição do
trial e doc_url apontando para esta seção. Corrija o método ou a configuração
do checkout; não repita automaticamente a mesma tentativa.
unsupported_currency
A moeda enviada não está entre as que a Chargefy processa. Hoje a API aceita sóbrl. Maiúsculas são aceitas e gravadas em minúsculas (BRL vira brl).
A regra vale para todo campo de moeda da entrada, como currency,
prices[].currency, line_items[].price_data.currency,
minimum_amount_currency e business_profile.annual_revenue.currency. A
resposta usa HTTP 400, type: "invalid_request_error" e param com o caminho
exato do campo, por exemplo line_items[0].price_data.currency. Nada é criado.
Repetir o mesmo pedido não resolve: envie brl ou, onde o campo é opcional,
omita-o para usar a moeda padrão da organização.
param é
currency e o erro fica em last_payment_error. Numa renovação de assinatura,
a fatura falha uma vez com esse erro, sem novas tentativas automáticas.
Request ID
Toda resposta pública inclui o headerX-Request-Id. Guarde esse valor nos seus
logs: ele ajuda o suporte da Chargefy a encontrar a request exata.
- O
X-Request-Id. - O horário aproximado da chamada.
- O endpoint chamado.
- O
error.coderecebido.
Tratamento recomendado
Exemplo simples em Node:Node
Boas práticas
- Faça lógica com
error.code, não comerror.message. - Mostre mensagens de cartão ao comprador com cuidado e sem expor detalhes sensíveis.
- Faça retry com backoff para
429e5xxapenas quando oerror.codepermitir.payment_result_unconfirmedexige consulta/reconciliação, nunca um novo write cego. - Não faça retry automático para
400,401,402,403ou404sem corrigir a causa. - Logue
X-Request-Idem todas as falhas.
Próximos passos
Autenticação
Corrija erros de credencial, escopo e organização.
Paginação
Entenda erros de cursor, limite e filtros.
Idempotência
Evite duplicar writes em retries.
Datas, fusos e moedas
Corrija erros de formato em
due_date.Requests
Consulte requests registrados na API.
installment_interest_changed
HTTP409: os juros mudaram desde a apresentação do preço, e nenhuma cobrança foi enviada nessa confirmação. Para um Payment Intent, atualize payment_method_options, apresente o total atualizado e confirme novamente. param é payment_method_options. Não repita automaticamente a confirmação sem revisar o valor.
Tabelas de juros no Chargefy for Platforms
Disponível somente no Chargefy for Platforms, para operar suas organizações filhas.
fee_plan atribuído a ela: installment_plan é somente leitura. Para mudar os juros, atribua outro plano.
Essas validações acontecem antes de gravar qualquer campo da requisição.

