> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://novita.ai/settings/key-management), 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](/docs/pt-BR/guides/llm-api-keys) 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](/docs/pt-BR/guides/llm-model-access) 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](/docs/pt-BR/guides/llm-model-access) 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.