Skip to main content
Pagou returns standard HTTP status codes and RFC 7807 application/problem+json bodies for most errors.

​
Retry matrix

StatusMeaningWhat to do
400malformed request or unsupported combinationfix the request before retrying
401 / 403auth or permission issuefix credentials or access configuration
404resource not foundverify the ID and tenant context
409duplicate or conflicting statereconcile instead of retrying blindly
422validation errorfix field data and resend
5xxtransient server issueretry 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": "req_1001",
  "data": {
    "id": "tr_1001",
    "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