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.

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.
`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.
`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.

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: "nome@email.com",
  }),
});

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

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Formato

Tipos de erro

Status HTTP

Exemplos comuns

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

​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

Request ID

Tratamento recomendado

Boas práticas

Próximos passos