Erros

Todo erro usa o mesmo envelope JSON — programe seu handler uma vez:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "fieldErrors": { "amount": ["must be greater than 0"] },
  "requestId": "a7b8c9d0-e1f2-4345-9012-345678901234"
}

fieldErrors aparece em 400 (validação) — mostre ao usuário, não repita o request.
requestId vem em todo erro (e no header x-request-id) — cite ao falar com o suporte.

Status

Código	Significado	Ação
`400`	Validação ou regra de negócio	Corrija o corpo (veja `message`/`fieldErrors`). Não repita igual.
`401`	Chave de API inválida/ausente	Verifique o header `apikey`.
`403`	Bloqueio antifraude/velocity (`fraud.*`)	Revise o cliente ou contate o suporte.
`404`	Recurso não encontrado	Verifique o `id`.
`409`	`idempotencyKey` reusada com corpo diferente	Use uma chave nova.
`429`	Rate limit	Faça backoff com jitter.
`5xx`	Erro interno PagNow	Reenvie com a mesma `idempotencyKey`.

observação

Regras de negócio (moeda não habilitada, valor abaixo do mínimo, CPF/CNPJ inválido, chave PIX inválida) são retornadas como 400 com uma message explicativa — não há um 422 separado.

Status​

Status