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

# Errors and Retries

> Interpret Pagou error responses and decide when to retry, fix input, or reconcile state.

Pagou returns standard HTTP status codes and RFC 7807 `application/problem+json` bodies for most errors.

## Retry matrix

| Status        | Meaning                                      | What to do                                                      |
| ------------- | -------------------------------------------- | --------------------------------------------------------------- |
| `400`         | malformed request or unsupported combination | fix the request before retrying                                 |
| `401` / `403` | auth or permission issue                     | fix credentials or access configuration                         |
| `404`         | resource not found                           | verify the ID and authenticated account                         |
| `409`         | duplicate or conflicting state               | reconcile instead of retrying blindly                           |
| `422`         | validation error                             | fix field data and resend                                       |
| `5xx`         | transient server issue                       | retry with backoff and reconcile if the write result is unknown |

## Example error response

```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"
    }
  ]
}
```

## Example fix

Request:

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

Response:

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

## Practical rules

* Never auto-retry `4xx` writes except behind explicit reconciliation logic.
* Use exponential backoff for `429` and `5xx` responses.
* If the response to a write is lost, retrieve the resource before creating another one.
* Log `requestId`, your `external_ref`, and the Pagou resource ID together.

## Next steps

* [Idempotency](/start-here/idempotency)
* [Webhook Fundamentals](/start-here/webhooks)
* [Retries and Reconciliation](/webhooks/retries-and-reconciliation)