Pular para o conteúdo principal
A Pagou devolve códigos HTTP padrão e corpos RFC 7807 application/problem+json na maioria dos erros.

​
Matriz de retry

StatusSignificadoO que fazer
400requisição malformada ou combinação não suportadacorrija a requisição antes de repetir
401 / 403problema de auth ou permissãoajuste credenciais ou configuração de acesso
404recurso não encontradovalide o ID e o contexto do tenant
409estado duplicado ou conflitantereconcilie em vez de repetir às cegas
422erro de validaçãocorrija os campos e envie de novo
5xxproblema transitório do servidorrepita com backoff e reconcilie se o resultado da escrita estiver incerto

​
Exemplo de resposta de erro

{
  "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: 
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}
Resposta: 
{
  "success": true,
  "requestId": "req_1001",
  "data": {
    "id": "tr_1001",
    "status": "pending"
  }
}

​
Regras práticas

  • Não faça auto-retry 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