Referência Técnica
Códigos de Erro
Referência completa de códigos de erro da API
Referência completa de todos os códigos de erro retornados pela API da Nuvende.
Códigos HTTP
2xx - Sucesso
| Código | Descrição |
|---|---|
200 | OK - Requisição bem-sucedida |
201 | Created - Recurso criado com sucesso |
202 | Accepted - Requisição aceita para processamento |
4xx - Erro do Cliente
| Código | Descrição | Solução |
|---|---|---|
400 | Bad Request | Verificar parâmetros da requisição |
401 | Unauthorized | Verificar token de autenticação |
403 | Forbidden | Verificar permissões |
404 | Not Found | Recurso não encontrado |
422 | Unprocessable Entity | Dados inválidos |
429 | Too Many Requests | Rate limit excedido |
5xx - Erro do Servidor
| Código | Descrição | Solução |
|---|---|---|
500 | Internal Server Error | Tentar novamente mais tarde |
502 | Bad Gateway | Problema de conectividade |
503 | Service Unavailable | Serviço temporariamente indisponível |
504 | Gateway Timeout | Timeout na requisição |
Códigos de Erro Específicos
Não use códigos inventados do tipo AUTH_001 / PIX_001 — a API v2 sinaliza sobretudo por HTTP status e envelope Pix (type, title, status, detail, violacoes).
Envelope típico (Contas, Cobranças, Pix)
Em várias rotas o corpo de erro segue o padrão abaixo (campos podem variar):
{
"type": "https://pix.bcb.gov.br/api/v2/error/OperacaoInvalida",
"title": "Operação inválida.",
"status": 422,
"detail": "Requisição no formato inválido, ou realizando alguma operação não permitida",
"violacoes": {
"data_inicio": ["The data inicio field is required."]
}
}
| Campo | Uso |
|---|---|
status | Espelha o HTTP na maioria dos casos |
title / detail | Mensagem legível |
violacoes | Erros de validação por campo (ex.: extrato sem data_inicio) |
correlationId | Pode aparecer em falhas 5xx |
Contas e Cobranças (orientação)
| HTTP | Situação frequente |
|---|---|
| 400 | Recurso inválido (ex.: conta não encontrada em GET /contas) |
| 401 | Token inválido |
| 403 | Scope ausente (contas.*, cob.*, pix.*, webhooks.*) |
| 422 | Validação de query/body (violacoes) |
| 429 | Rate limit |
Checklist por área: Resolução de problemas.
Tratamento de Erros
JavaScript/Node.js
function tratarErro(error) {
const status = error.response?.status;
const codigo = error.response?.data?.codigo;
switch (status) {
case 400:
console.error('Parâmetros inválidos');
break;
case 401:
console.error('Token inválido');
break;
case 403:
console.error('Permissões insuficientes');
break;
case 404:
console.error('Recurso não encontrado');
break;
case 429:
console.error('Rate limit excedido');
break;
case 500:
console.error('Erro interno do servidor');
break;
default:
console.error('Erro inesperado:', error.message);
}
}