Erros HTTP da API

A API usa o status HTTP e um corpo JSON para explicar cada falha. Leia os dois antes de repetir a chamada.

{
  "error": true,
  "message": "Token de autenticação não fornecido",
  "code": "MISSING_TOKEN"
}

Resposta rápida

Erro 400

O status 400 indica que a API entendeu a chamada, mas não pode executá-la. O campo code informa a regra que falhou.

Os códigos mais comuns são:

• BAD_REQUEST: a chamada tem um formato inválido.
• VALIDATION_ERROR: um parâmetro não passou pela validação.
• QUOTES_PER_REQUEST_EXCEEDED: a chamada pediu ativos demais.
• INVALID_RANGE: o período não está disponível no plano.
• INVALID_INTERVAL: o intervalo não está disponível no plano.

Não repita a mesma chamada. Corrija o parâmetro indicado na mensagem.

Use o OpenAPI para conferir nomes, formatos e valores aceitos.

Erro 401

O status 401 indica um problema de autenticação.

MISSING_TOKEN significa que a chamada não enviou um token. INVALID_TOKEN significa que a API não aceitou o token enviado.

Envie o token no header:

curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4" \
  -H "Authorization: Bearer SEU_TOKEN"

Confira estes pontos:

1. O valor começa com Bearer .
2. O token não tem aspas, espaços extras ou quebras de linha.
3. A aplicação lê a variável de ambiente correta.
4. O token continua ativo no painel.

PETR4, MGLU3, VALE3 e ITUB4 funcionam no sandbox sem token.

Leia também Autenticação e tokens.

Erro 403

O status 403 indica que a autenticação funcionou, mas o plano não libera o recurso pedido.

O código pode ser FEATURE_NOT_AVAILABLE, MODULES_NOT_AVAILABLE ou outro código específico da regra. A resposta pode incluir details com o limite atual e a opção necessária.

Remova o módulo ou o dado bloqueado. Você também pode comparar os limites dos planos.

Não gere outro token. Um novo token da mesma conta mantém o mesmo plano.

Erro 404

O status 404 indica que a rota ou o recurso pedido não existe. A resposta usa o código NOT_FOUND.

Confira o domínio, a versão, o caminho e o identificador. Use /api/v2/... nas novas integrações.

Consulte a lista atual de rotas no OpenAPI.

Erro 429

O status 429 indica que a chamada atingiu a cota mensal, a simultaneidade ou o limite do sandbox.

Leia estes headers:

Se X-Brapi-Concurrency-Limit estiver presente, reduza o número de chamadas paralelas. Aguarde o valor de Retry-After antes de tentar novamente.

const response = await fetch(url, { headers });

if (response.status === 429) {
  const retryAfter = Number(response.headers.get('Retry-After') ?? '60');
  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1_000));
}

Não use um loop sem espera. Isso aumenta a fila e atrasa a recuperação.

Erros 500 e 503

Os status 500 e 503 indicam uma falha temporária no processamento ou na obtenção de um dado necessário.

Use estas regras:

1. Espere antes da primeira repetição.
2. Aumente o atraso a cada tentativa.
3. Adicione uma pequena variação aleatória ao atraso.
4. Limite o número de tentativas.
5. Registre status, code, rota e horário.

Não registre o token. Remova dados pessoais antes de enviar um relato.

Se a falha continuar, consulte o status do serviço e envie o contexto pelo contato.

O que repetir

Chamadas de leitura podem ser repetidas. Para qualquer operação de escrita, confirme a política do endpoint antes de repetir.

Checklist para pedir ajuda

Envie estas informações:

• rota sem query sensível;
• método HTTP;
• status HTTP;
• valor de code;
• horário com fuso;
• identificador da resposta, quando disponível;
• exemplo mínimo que reproduz a falha.

Nunca envie o token, cookies ou dados pessoais.