Skip to main content
Erros da API pública seguem sempre o mesmo formato. O objeto error traz o tipo do erro, um código estável e uma mensagem legível. 
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.chargefy.io/api-reference/errors",
    "message": "Missing required param: amount.",
    "param": "amount",
    "request_log_url": "https://dashboard.chargefy.io/request-logs/req_123",
    "type": "invalid_request_error"
  }
}

​
Campos

​
error.type
string
Categoria do erro.
​
error.code
string
Código estável para tratamento programático.
​
error.message
string
Mensagem em inglês explicando o problema.
​
error.param
string
Campo relacionado ao erro, quando aplicável.
​
error.doc_url
string
Link para documentação adicional, quando aplicável.
​
error.request_log_url
string
Link para abrir o request no dashboard, quando disponível.

​
Tipos de erro

TypeQuando acontece
invalid_request_errorParâmetro inválido, ausente, conflito de estado ou ação não permitida.
authentication_errorAPI key ausente, inválida, expirada ou sem permissão.
card_errorErro de cartão ou falha financeira retornada ao tentar pagar ou salvar cartão.
rate_limit_errorMuitas requisições em pouco tempo.
api_errorErro inesperado na Chargefy.

​
Status HTTP

StatusUso comum
200Request concluída com sucesso. Creates, updates e actions retornam o objeto completo.
400Request inválida.
401Credencial ausente ou inválida.
402Falha de pagamento ou cartão recusado.
403Credencial sem permissão suficiente.
404Recurso não encontrado.
409Conflito com o estado atual do recurso.
422Payload bem formado, mas não processável.
429Rate limit excedido.
500Erro interno. Tente novamente com backoff.

​
Boas práticas

  • Use error.code para lógica no seu sistema.
  • Mostre error.message para logs e debugging.
  • Informe o header Request-Id ou o error.request_log_url ao falar com suporte.
  • Implemente retry com backoff para 429 e erros 5xx.
  • Não faça retry automático em card_error sem ação do comprador.