> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Formato de erro da API.

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.

<ResponseExample>
  ```json theme={}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Campos

<ResponseField name="error.type" type="string">
  Categoria do erro.
</ResponseField>

<ResponseField name="error.code" type="string">
  Código estável para tratamento programático.
</ResponseField>

<ResponseField name="error.message" type="string">
  Mensagem em inglês explicando o problema.
</ResponseField>

<ResponseField name="error.param" type="string">
  Campo relacionado ao erro, quando aplicável.
</ResponseField>

<ResponseField name="error.doc_url" type="string">
  Link para documentação adicional, quando aplicável.
</ResponseField>

<ResponseField name="error.request_log_url" type="string">
  Link para abrir o request no dashboard, quando disponível.
</ResponseField>

## Tipos de erro

| Type                    | Quando acontece                                                                |
| ----------------------- | ------------------------------------------------------------------------------ |
| `invalid_request_error` | Parâmetro inválido, ausente, conflito de estado ou ação não permitida.         |
| `authentication_error`  | API key ausente, inválida, expirada ou sem permissão.                          |
| `card_error`            | Erro de cartão ou falha financeira retornada ao tentar pagar ou salvar cartão. |
| `rate_limit_error`      | Muitas requisições em pouco tempo.                                             |
| `api_error`             | Erro inesperado na Chargefy.                                                   |

## Status HTTP

| Status | Uso comum                                                                             |
| ------ | ------------------------------------------------------------------------------------- |
| `200`  | Request concluída com sucesso. Creates, updates e actions retornam o objeto completo. |
| `400`  | Request inválida.                                                                     |
| `401`  | Credencial ausente ou inválida.                                                       |
| `402`  | Falha de pagamento ou cartão recusado.                                                |
| `403`  | Credencial sem permissão suficiente.                                                  |
| `404`  | Recurso não encontrado.                                                               |
| `409`  | Conflito com o estado atual do recurso.                                               |
| `422`  | Payload bem formado, mas não processável.                                             |
| `429`  | Rate limit excedido.                                                                  |
| `500`  | Erro 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.