Errors and Retries

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

{
  "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:

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

Response:

{
  "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.

Getting Started

Going to Production

AI-Assisted Integration

Retry matrix

Example error response

Example fix

Practical rules

Next steps

​Retry matrix

​Example error response

​Example fix

​Practical rules

​Next steps

Retry matrix

Example error response

Example fix

Practical rules

Next steps