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

# Tratar erros da API

> Use o código HTTP e o corpo para decidir entre correção, nova tentativa e investigação.

| HTTP | Significado | Ação do cliente |
| - | - | - |
| 400 | O processador rejeitou a operação e o Gateway traduziu a falha. | Registre o corpo e não repita sem entender a causa. |
| 401 | O token está ausente, inválido ou sem acesso. | Corrija a credencial e remova `Origin` das chamadas entre servidores. |
| 403 | A operação não está disponível para o tipo de estabelecimento. | Não repita sem alterar o credenciamento. |
| 404 | O recurso ou a configuração consultada não existe no escopo autenticado. | Confirme o identificador e o processador. |
| 409 | O domínio ou o processador detectou um conflito. | Consulte a transação antes de criar outra. |
| 422 | Um campo é inválido ou uma capacidade Pix não está disponível. | Corrija os dados ou a configuração indicada. |
| 429 | O limite da rota foi excedido. | Espere e aplique recuo antes de tentar novamente. |
| 500 | Uma falha interna ou não traduzida interrompeu a operação. | Consulte pelo identificador do estabelecimento antes de repetir uma escrita. |

## Erro de validação

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}
```

Falhas tratadas pelo `Handler` usam o envelope `error`, com o código repetido em `status`. O valor de `message` pode ser texto ou um mapa de campos.

```json theme={null}
{
  "error": {
    "message": {
      "base": [
        "Pix processor not found."
      ]
    },
    "status": 422
  }
}
```

O endpoint de reembolso captura erros do processador dentro do próprio controller. Nessa operação específica, HTTP 422 e HTTP 500 usam um corpo simples com `message`, conforme os exemplos da referência.

## Repetir uma escrita

Antes de repetir uma criação após timeout ou HTTP 500, consulte a transação pelo `merchant_transaction_id`. Uma falha de transporte não prova que a primeira tentativa não produziu efeito.

> [!NOTE]
>
> Em `report_financial_info`, o corpo recebe `timestamp`, mas um erro de validação de data pode usar a chave `external_timestamp`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.