Pular para o conteúdo principal
Quando uma request falha, a API da Chargefy responde com duas informações:
  • Um status HTTP, como 400, 401 ou 404, que diz a classe do problema.
  • Um objeto error, em JSON, com um code estável e uma mensagem legível.
O ponto mais importante: use 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

string
Código estável para tratamento programático. Exemplo: parameter_missing, authentication_failed, resource_missing.
string | null
Link para documentação adicional, quando disponível.
string
Texto em inglês explicando o problema. A mensagem pode mudar para ficar mais clara; não faça lógica usando essa string.
string | null
Campo relacionado ao erro, quando aplicável. Pode ser um campo do body, query param ou header.
string
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 HTTP 409 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.
Com bloqueio de conta, a API responde HTTP 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 HTTP 409 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. Em brl, 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 de amount_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 em brl. 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 informa currency 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.
O mesmo código aparece ao confirmar um pagamento existente numa moeda que a Chargefy não processa: a cobrança não é enviada ao processamento, 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 header X-Request-Id. Guarde esse valor nos seus logs: ele ajuda o suporte da Chargefy a encontrar a request exata.
Quando abrir um chamado, envie:
  • O X-Request-Id.
  • O horário aproximado da chamada.
  • O endpoint chamado.
  • O error.code recebido.

Tratamento recomendado

Exemplo simples em Node:
Node

Boas práticas

  • Faça lógica com error.code, não com error.message.
  • Mostre mensagens de cartão ao comprador com cuidado e sem expor detalhes sensíveis.
  • Faça retry com backoff para 429 e 5xx apenas quando o error.code permitir. payment_result_unconfirmed exige consulta/reconciliação, nunca um novo write cego.
  • Não faça retry automático para 400, 401, 402, 403 ou 404 sem corrigir a causa.
  • Logue X-Request-Id em 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

HTTP 409: 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.
A tabela de juros de uma organização filha vem do 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.