Erros comuns da API Pix
Resposta rápida: Erros da API Pix seguem RFC 7807 com
typeno padrãohttps://pix.bcb.gov.br/api/v2/error/<TipoErro>; 4xx é problema do cliente, 5xx do servidor.
Tipos gerais (BACEN)
| Tipo | HTTP | Significado prático |
|---|---|---|
| RequisicaoInvalida | 400 | JSON/campos inválidos |
| (OAuth) invalid_scope | 401 | scope pedido que a credencial não tem — não envie scope |
| (OAuth) invalid_client | 401 | Credenciais em Basic auth; mande-as no corpo da requisição |
| AcessoNegado | 403 | Autenticado sem permissão / produto não contratado |
| NaoEncontrado | 404 | txid ou recurso inexistente |
| ErroInternoDoServidor | 500 | Falha no PSP |
| ServicoIndisponivel | 503 | Manutenção / fora da janela |
Erros antes do HTTP
Falha de TLS não tem body para ler, e por isso é confundida com credencial errada:
| Sintoma | Causa | Ação |
|---|---|---|
unable to get local issuer certificate | CA do banco ausente no cliente | Passar {{PATH_TO_CA}} — mTLS |
handshake failure com CA presente | Cert/key errados ou expirados | Conferir par e validade |
O que fazer primeiro
- Ler
status,title,detaildo body. Se não houver body, o problema é TLS, não HTTP. - Conferir mTLS (cert, key e CA) + Bearer.
- Validar payload contra OpenAPI BACEN.
Usado em
- Seções “Se der errado” das recipes