Códigos de erro comuns

Este documento resume os códigos de erro mais comuns retornados pela plataforma da API Novita, junto com definições, causas e soluções recomendadas para ajudar os usuários a solucionar problemas com eficiência.

---

​

Código de erro 400

Descrição: Parâmetros de solicitação inválidos.
Solução:
Revise os detalhes da mensagem de erro e verifique se os formatos dos parâmetros, nomes de campos ou intervalos de valores estão em conformidade com a documentação da API.

---

​

Código de erro 401

Descrição: A chave de API está ausente ou incorreta.
Causas comuns:

• Chave ausente: sem o cabeçalho Authorization, ou o cabeçalho não está no formato Authorization: Bearer <API Key>.
• Chave incorreta ou malformada: um erro de digitação, espaço em branco extra ou um valor que não é uma chave sk_ válida.
• Chave excluída: a chave foi excluída em Gerenciamento de Chaves, portanto ela não autentica mais.

Solução:

• Certifique-se de que a chave de API seja fornecida na solicitação e use o esquema Bearer;
• Verifique se a chave de API está correta e ainda existe no Gerenciamento de Chaves;
• Se estiver usando variáveis de ambiente ou arquivos de configuração, confirme se eles estão sendo lidos corretamente durante a execução. Consulte Chaves de API para saber como armazenar e carregar uma chave.

---

​

Código de erro 403

Descrição: Acesso negado devido a permissões insuficientes.

​

Acesso ao modelo negado (model_access_denied)

A chave de API é válida, mas não tem permissão para chamar o modelo solicitado. O acesso ao modelo da chave é restrito, e o modelo solicitado está fora do seu intervalo. Solução:

• Chame um modelo que esteja dentro do intervalo de acesso da chave, ou
• Peça ao administrador da sua equipe para ajustar o acesso ao modelo da chave para incluir o modelo.

​

O modelo exige verificação de identidade

Alguns modelos exigem verificação de identidade antes que sua conta possa acessá-los. Solução:

• Verifique se sua conta associada à chave de API tem permissão para acessar o modelo solicitado;
• Faça login no console e verifique o status de verificação da sua conta;
• Se não estiver verificada, conclua a verificação de identidade primeiro;
• Como alternativa, use uma chave de API de uma conta já verificada.

---

​

Código de erro 429

Descrição: Limite de taxa excedido (Too Many Requests).
Solução:

• Verifique se o limite se deve a TPM (tokens por minuto) ou RPM (solicitações por minuto);
• Consulte a documentação oficial de Limites de Taxa;
• Para aumentar seu limite de taxa, entre em contato com o suporte ou use uma conta verificada.

---

​

Código de erro 503 / 504

Descrição: Timeout do backend ou serviço indisponível, geralmente causado por alta carga do sistema ou limitação.

​

Possíveis causas:

• Sobrecarga de GPU ou CPU nos nós de serviço do modelo;
• Tempo de geração longo em solicitações sem streaming excede o timeout do gateway;
• Falhas em serviços downstream (por exemplo, Redis, mecanismo do modelo);
• O módulo de modelagem de tráfego ativou a proteção contra picos e retornou 503.

​

Soluções recomendadas:

Para usuários da API:

• Habilite o mecanismo de repetição: use backoff exponencial para evitar sobrecarga repetida;
• Mude para o modo streaming: respostas em streaming retornam tokens conforme são gerados, reduzindo a latência e o risco de timeout;
• Otimize as configurações do cliente: certifique-se de que client_timeout e proxy_timeout excedam 60 segundos;
• Evite períodos de pico: em cenários de alta concorrência, tente novamente fora dos horários de pico.

Para operações da plataforma:

• Aprimore o monitoramento e o autoescalonamento dos serviços de modelo;
• Ajuste adequadamente o proxy_read_timeout no nível do gateway;
• Implemente regras de limitação refinadas (por exemplo, filas de prioridade, priorização de negócios principais);
• Use Prometheus + Alertmanager para acionar alertas em picos de 503/504.

---

​

Código de erro 500

Descrição: Erro interno do servidor — normalmente causado por exceções no backend ou falhas no mecanismo do modelo.
Solução:

• Esses problemas geralmente exigem resolução do lado da plataforma. Entre em contato com o suporte para investigar logs e recursos do sistema;
• Opcionalmente, tente mudar de modelo ou usar como fallback uma configuração que exija menos recursos.

---

​

Outros erros

Para erros indefinidos ou não documentados:

• Primeiro, consulte o campo message na resposta da API;
• Em seguida, verifique os logs da solicitação ou os rastros do console;
• Por fim, entre em contato com o suporte da Novita ou envie um ticket para obter assistência adicional.