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

# Erros e retentativas

> Interprete respostas de erro da Pagou e saiba quando corrigir payload, repetir ou reconciliar.

A Pagou devolve códigos HTTP padrão e corpos RFC 7807 `application/problem+json` na maioria dos erros.

## Matriz de retentativa

| Status        | Significado                                       | O que fazer                                                               |
| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| `400`         | requisição malformada ou combinação não suportada | corrija a requisição antes de repetir                                     |
| `401` / `403` | problema de autenticação ou permissão             | ajuste credenciais ou configuração de acesso                              |
| `404`         | recurso não encontrado                            | valide o ID e a conta autenticada                                         |
| `409`         | estado duplicado ou conflitante                   | reconcilie em vez de repetir às cegas                                     |
| `422`         | erro de validação                                 | corrija os campos e envie de novo                                         |
| `5xx`         | problema transitório do servidor                  | repita com backoff e reconcilie se o resultado da escrita estiver incerto |

## Exemplo de resposta de erro

```json theme={null}
{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "buyer.email",
      "message": "Invalid email format",
      "code": "invalid_string"
    }
  ]
}
```

## Exemplo corrigido

Requisição:

```json theme={null}
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}
```

Resposta:

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "pending"
  }
}
```

## Regras práticas

* Não faça retentativa automática de escritas `4xx`, exceto atrás de lógica explícita de reconciliação.
* Use backoff exponencial para respostas `429` e `5xx`.
* Se a resposta de uma escrita se perder, consulte o recurso antes de criar outro.
* Registre `requestId`, seu `external_ref` e o ID do recurso da Pagou juntos.

## Próximos passos

* [Idempotência](/pt/start-here/idempotency)
* [Fundamentos de webhook](/pt/start-here/webhooks)
* [Retentativas e reconciliação](/pt/webhooks/retries-and-reconciliation)