Erros

Falhas usam envelope padronizado e incluem request_id.

{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_..."
  }
}

Toda resposta carrega o header X-Request-Id. Informe esse ID ao suporte para agilizar a investigação.

Códigos HTTP

HTTP	Quando acontece
`401`	Token ausente, inválido ou revogado
`403`	Conta sem KYC, IP fora da allowlist ou permissão insuficiente
`404`	Recurso inexistente ou de outra loja
`409`	Idempotência divergente
`422`	Validação ou pedido recusado
`503`	Plataforma/adquirente indisponível

Código	HTTP	Causa
`validation_failed`	422	Campo inválido; veja `error.fields`
`amount_below_minimum`	422	Valor abaixo do ticket mínimo do PIX
`amount_above_maximum`	422	Valor acima do ticket máximo do PIX
`payment_not_cancellable`	422	Cobrança não está em `waiting_payment`
`idempotency_mismatch`	409	Mesma chave com corpo diferente
`platform_unavailable`	503	Adquirente escolhido não está conectado

Recurso de outra loja responde 404, não 403, inclusive entre lojas do mesmo usuário.