Códigos de error
Qué significan 401 / 403 / 404 / 429 / 5xx, un diagnóstico en cinco pasos y prácticas que evitan errores.
Cuando falla una llamada, empieza por el código de estado HTTP y el mensaje de error del cuerpo de la respuesta, y compáralos con la tabla siguiente. La mayoría de los problemas se resuelven con los tres primeros puntos.
Códigos de estado
| Estado | Significado | Causas habituales y soluciones |
|---|---|---|
| 400 Bad Request | Solicitud no válida | JSON mal formado o falta un campo obligatorio (model, messages); contrasta el cuerpo con la documentación de la API |
| 401 Unauthorized | Autenticación fallida | La clave es incorrecta, se ha eliminado o ha caducado; consulta la lista de comprobación en Autenticación |
| 403 Forbidden | Sin acceso | Puede que esta clave o cuenta no pueda llamar al modelo solicitado; confirma en el catálogo que el modelo está disponible para ti |
| 404 Not Found | Recurso no encontrado | Normalmente un ID de modelo mal escrito; copia el ID exacto del catálogo de modelos |
| 429 Too Many Requests | Límite de peticiones alcanzado | Las solicitudes son demasiado frecuentes. Aplica retroceso (intervalos exponenciales) o reduce la concurrencia; contacta con la plataforma si persiste |
| 5xx | Error del servidor | Un fallo temporal de la plataforma o del modelo de origen. Reintenta una vez con los mismos parámetros; si sigue fallando, contacta con Soporte con los registros de la solicitud de la página de Registros |
Pasos de diagnóstico
- Verifica la clave: confirma en la página «Claves de API» que la clave existe y no ha caducado; elimínala y vuelve a crearla si tienes dudas.
- Verifica el ID del modelo: cópialo del catálogo de modelos en lugar de escribirlo a mano.
- Lee el cuerpo del error: las respuestas de error suelen incluir
error.messageexplicando la causa exacta (saldo insuficiente, parámetro ausente, etc.). - Revisa los registros: la página de Registros de la consola muestra el estado, la latencia y el consumo de cada solicitud; comprueba si el fallo se limita a un modelo o a una clave.
- Si sigues atascado: contacta con Soporte con las marcas de tiempo y los códigos de estado de la página de Registros.
Prácticas que evitan errores
- Usa un SDK oficial (gestiona por ti los reintentos, los tiempos de espera y los detalles del protocolo);
- Implementa retroceso exponencial para los 429 / 5xx en lugar de insistir con reintentos agresivos;
- Define un límite de gasto en las claves de producción para que un tráfico anómalo no vacíe el saldo.