> ## 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 error comunes

Este documento resume los códigos de error más comunes devueltos por la plataforma de la API de Novita, junto con definiciones, causas y soluciones recomendadas para ayudar a los usuarios a solucionar problemas de forma eficiente.

***

## Código de error 400

**Descripción**: Parámetros de solicitud no válidos.\
**Solución**:\
Revise los detalles del mensaje de error y compruebe si los formatos de los parámetros, los nombres de los campos o los rangos de valores cumplen con la documentación de la API.

***

## Código de error 401

**Descripción**: Falta la API Key o es incorrecta.\
**Causas comunes**:

* **Clave faltante**: no hay encabezado `Authorization`, o el encabezado no tiene el formato `Authorization: Bearer <API Key>`.
* **Clave incorrecta o mal formada**: un error tipográfico, espacios en blanco adicionales o un valor que no es una clave `sk_` válida.
* **Clave eliminada**: la clave se eliminó en [Administración de claves](https://novita.ai/settings/key-management), por lo que ya no autentica.

**Solución**:

* Asegúrese de que la API Key se proporcione en la solicitud y use el esquema `Bearer`;
* Verifique que la API Key sea correcta y aún exista en Administración de claves;
* Si usa variables de entorno o archivos de configuración, confirme que se estén leyendo correctamente durante la ejecución. Consulte [API Keys](/docs/es/guides/llm-api-keys) para saber cómo almacenar y cargar una clave.

***

## Código de error 403

**Descripción**: Acceso denegado debido a permisos insuficientes.

### Acceso al modelo denegado (`model_access_denied`)

La clave de API es válida, pero no tiene permitido llamar al modelo solicitado. El [acceso a modelos](/docs/es/guides/llm-model-access) de la clave está restringido, y el modelo solicitado está fuera de su rango.

**Solución**:

* Llame a un modelo que esté dentro del rango de acceso de la clave, o
* Pida al administrador de su equipo que ajuste el [acceso a modelos](/docs/es/guides/llm-model-access) de la clave para incluir el modelo.

### El modelo requiere verificación de identidad

Algunos modelos requieren verificación de identidad antes de que su cuenta pueda acceder a ellos.

**Solución**:

* Verifique que su cuenta asociada con la API Key tenga permiso para acceder al modelo solicitado;
* Inicie sesión en la consola y compruebe el estado de verificación de su cuenta;
* Si no está verificada, complete primero la verificación de identidad;
* Como alternativa, use una API Key de una cuenta ya verificada.

***

## Código de error 429

**Descripción**: Límite de tasa excedido (demasiadas solicitudes).\
**Solución**:

* Compruebe si el límite se debe a **TPM** (tokens por minuto) o **RPM** (solicitudes por minuto);
* Consulte la documentación oficial sobre límites de tasa;
* Para aumentar su límite de tasa, contacte con soporte o use una cuenta verificada.

***

## Código de error 503 / 504

**Descripción**: Tiempo de espera del backend agotado o servicio no disponible, a menudo causado por una alta carga del sistema o limitación de tráfico.

### Posibles causas:

* Sobrecarga de GPU o CPU en los nodos del servicio de modelos;
* El tiempo de generación prolongado en solicitudes sin streaming supera el tiempo de espera de la puerta de enlace;
* Fallos en servicios dependientes (por ejemplo, Redis, motor del modelo);
* El módulo de control de tráfico activó la protección contra picos y devolvió 503.

### Soluciones recomendadas:

**Para usuarios de la API**:

* **Habilitar un mecanismo de reintento**: Use retroceso exponencial para evitar sobrecargas repetidas;
* **Cambiar al modo streaming**: Las respuestas en streaming devuelven tokens a medida que se generan, reduciendo la latencia y el riesgo de tiempo de espera;
* **Optimizar la configuración del cliente**: Asegúrese de que `client_timeout` y `proxy_timeout` superen los 60 segundos;
* **Evitar los períodos pico**: Para escenarios de alta concurrencia, vuelva a intentarlo fuera de las horas pico.

**Para operaciones de plataforma**:

* Mejorar la supervisión y el autoescalado de los servicios de modelos;
* Ajustar adecuadamente `proxy_read_timeout` a nivel de puerta de enlace;
* Implementar reglas de limitación de tráfico granulares (por ejemplo, colas de prioridad, priorización del negocio principal);
* Usar Prometheus + Alertmanager para activar alertas ante picos de 503/504.

***

## Código de error 500

**Descripción**: Error interno del servidor, normalmente causado por excepciones del backend o bloqueos del motor del modelo.\
**Solución**:

* Estos problemas normalmente requieren resolución del lado de la plataforma. Contacte con soporte para investigar los registros y los recursos del sistema;
* Opcionalmente, intente cambiar de modelo o usar como alternativa una configuración que consuma menos recursos.

***

## Otros errores

Para errores no definidos o no documentados:

* Primero, consulte el campo `message` en la respuesta de la API;
* Luego, revise los registros de solicitudes o los rastros de la consola;
* Finalmente, contacte con el soporte de Novita o envíe un ticket para obtener más ayuda.