Erros

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

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.chargefy.io/api-reference/errors",
    "message": "Missing required param: amount.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

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

`type`	O que significa	O que fazer
`invalid_request_error`	A request está incompleta, inválida ou conflita com o estado atual do recurso.	Corrija parâmetro, body, cursor, estado ou rota chamada.
`authentication_error`	A API key está ausente, inválida, expirada, sem escopo ou sem acesso ao recurso.	Corrija a chave, escopo ou header `Organization`.
`card_error`	O cartão ou a tentativa de pagamento foi recusado ou não pôde ser processado.	Mostre uma ação clara para o comprador: revisar dados, tentar outro cartão ou usar outro método.
`rate_limit_error`	Muitas requests em pouco tempo.	Espere e tente de novo com backoff.
`api_error`	Erro inesperado, indisponibilidade temporária ou resultado financeiro ainda em confirmação.	Leia o `code`: faça retry com backoff somente quando ele permitir; para resultado não confirmado, consulte o recurso sem repetir a operação.

Status HTTP

Status	Quando aparece	Retry automático?
`200`	Sucesso. Creates, updates e actions também retornam `200`.	Não se aplica.
`400`	Parâmetro ausente, JSON inválido, cursor inválido ou combinação proibida.	Não. Corrija a request.
`401`	API key ausente, inválida, revogada ou expirada.	Não. Corrija a credencial.
`402`	Falha de cartão ou pagamento.	Não sem ação do comprador.
`403`	Chave válida, mas sem permissão, escopo ou organização acessível.	Não. Corrija escopo/acesso.
`404`	Recurso não encontrado no escopo da chave.	Não. Verifique o ID e o ambiente.
`409`	Conflito com o estado atual do recurso.	Depende do `code`; em geral, resolva o estado antes.
`413`	Body grande demais.	Não. Reduza o payload ou arquivo.
`422`	Payload bem formado, mas não processável naquele contexto.	Não. Corrija os dados.
`429`	Rate limit excedido.	Sim, com backoff.
`500`	Erro interno.	Sim, com backoff.

Exemplos comuns

Use esta tabela para reconhecer a causa e decidir a ação sem abrir vários blocos de exemplo:

Status e `error.code`	Quando acontece e como tratar
`400 parameter_missing`	Um campo obrigatório não foi enviado no body ou na query; `error.param` identifica o campo quando disponível. Como tratar: corrija a request antes de tentar novamente.
`400 parameter_invalid`	Um campo foi enviado com valor que não passa na validação, como um `customer_document` sem dígito verificador válido; `error.param` identifica o campo. Como tratar: valide o valor antes de reenviar.
`401 authentication_failed`	A API key está ausente, inválida, expirada ou revogada. Como tratar: confira o header, o ambiente e o estado da credencial.
`402 invalid_cvc` ou outro código de cartão	O cartão não pôde ser processado; o `code` informa a causa pública disponível. Como tratar: oriente o comprador a revisar os dados, tentar outro cartão ou escolher outro método.
`403 permission_denied`	A chave é válida, mas não tem escopo ou acesso ao contexto solicitado. Como tratar: use o escopo correto ou, no Chargefy for Platforms, uma organização filha acessível.
`404 resource_missing`	O ID não existe, pertence a outro ambiente ou está fora do alcance da chave. Como tratar: confira o ID, o ambiente e o contexto da organização.
`409` com código específico	A operação conflita com o estado atual ou com outra request em andamento. Como tratar: leia o `code` e resolva o estado antes de repetir.
`400 installment_count_exceeds_maximum`	O `count` do plano de parcelamento passa da regra efetiva (máximo da organização, meses do período ou R$ 7,00 por parcela). Como tratar: ofereça no máximo o teto informado na mensagem.
`400 subscription_installments_not_supported`	Parcelamento pedido para um plano inelegível — mensal ou mais curto, com item medido, ou cobrado por fatura. Como tratar: envie a assinatura à vista (omita `payment_settings`).
`400 invoice_item_price_must_be_one_time`	Um preço recorrente foi enviado em `add_invoice_items`. Como tratar: use um preço avulso (`type: one_time`) para a cobrança inicial.
`400 subscription_interval_change_not_supported`	Tentativa de alterar a cadência de uma assinatura existente. Como tratar: crie uma nova assinatura após o término da atual.
`429 rate_limit_exceeded`	A integração excedeu o limite de requests. Como tratar: faça retry com backoff exponencial e jitter.
`500 internal_error`	Houve uma falha temporária ou inesperada; detalhes internos não são expostos. Como tratar: faça retry com backoff e, se persistir, envie o `X-Request-Id` ao suporte.
`502 payment_result_unconfirmed`	A tentativa pode ter chegado ao processamento, mas a resposta final não voltou. Como tratar: não repita o write; consulte o recurso e aguarde o webhook.

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.

Método	Regras que precisam ser satisfeitas	Consequência prática
Pix	Cobrir a tarifa do plano efetivo da organização	Com tarifa de R $1,00, R$ 1,00 passa; com 0,50% + R $1,00, o mínimo é R$ 1,01
Boleto	Cobrir a tarifa do plano e atingir R$ 3,00	Se a tarifa fixa for R $4,00, o mínimo é R$ 4,00
Cartão de crédito	Cobrir a tarifa do plano e atingir R$ 7,00 por parcela sobre o principal	Em 2 parcelas, o principal precisa atingir R$ 14,00, mesmo com juros ou repasse

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.

{
  "error": {
    "code": "amount_too_small",
    "currency": "brl",
    "doc_url": "https://docs.chargefy.io/api-reference/errors#amount-too-small",
    "message": "pix amount (100 cents) is below the minimum of 101 cents for this organization.",
    "minimum_amount": 101,
    "param": "amount",
    "payment_method_type": "pix",
    "requested_amount": 100,
    "type": "invalid_request_error"
  }
}

Campo	Tipo	Significado
`requested_amount`	integer	Total que seria cobrado do comprador, em centavos
`minimum_amount`	integer	Menor total aceito nesta cotação, em centavos
`payment_method_type`	string	`credit_card`, `pix` ou `boleto`
`currency`	string	Moeda em minúsculas, como `brl`

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.

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.

X-Request-Id: {{X_REQUEST_ID}}

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

const response = await fetch("https://api.chargefy.io/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHARGEFY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[email protected]",
  }),
});

const payload = await response.json();

if (!response.ok) {
  const code = payload.error?.code;
  const requestId = response.headers.get("X-Request-Id");

  console.error("Chargefy request failed", {
    code,
    message: payload.error?.message,
    requestId,
  });

  if (response.status === 429 || response.status >= 500) {
    // agende um retry com backoff exponencial
  }
}

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.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Formato

Tipos de erro

Status HTTP

Exemplos comuns

amount_too_small

payment_method_not_allowed

Request ID

Tratamento recomendado

Boas práticas

Próximos passos

Autenticação

Paginação

Idempotência

Datas, fusos e moedas

Requests

​Formato

​Tipos de erro

​Status HTTP

​Exemplos comuns

​amount_too_small

​payment_method_not_allowed

​Request ID

​Tratamento recomendado

​Boas práticas

​Próximos passos

Autenticação

Paginação

Idempotência

Datas, fusos e moedas

Requests

Formato

Tipos de erro

Status HTTP

Exemplos comuns

amount_too_small

payment_method_not_allowed

Request ID

Tratamento recomendado

Boas práticas

Próximos passos