Skip to main content
The Pagou API uses standard HTTP status codes and may return RFC 7807 application/problem+json payloads for errors.

​
Retry matrix

StatusMeaningWhat you should do
400malformed request or unsupported combinationfix the request before retrying
401 / 403authentication or permission problemrotate credentials or fix access configuration
404resource not foundverify the ID and tenant context on your side
409duplicate or conflicting statereconcile with the existing resource instead of retrying blindly
422validation failureinspect field-level errors and correct payload data
5xxtransient server problemretry with backoff and reconcile if the write outcome is uncertain

​
Problem Details example

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

​
Practical retry policy

  • Never retry 4xx write errors automatically except after explicit reconciliation logic.
  • Back off and retry 5xx responses.
  • If you lose the response to a write, fetch the resource before creating a new one.
  • Keep request IDs and resource IDs in logs for support escalation.