Troubleshooting

Soluciones a los problemas más comunes al usar la API de AstrApp, con el mensaje que vas a ver en cada caso.

Autenticación

401 Missing authentication

La petición no trae el header Authorization ni una sesión de la app. Agrega tu API Key con el prefijo Bearer.

401 Invalid token or session

El servidor no reconoce la key. Las causas más comunes:

La key se copió incompleta, venció, está desactivada o la eliminaste.
Escribiste bearer en minúsculas o dejaste un espacio de más: el servidor espera exactamente Bearer seguido de la key.
Mandaste un token de sesión en vez de una API Key: el header solo acepta keys.

bash

# Correcto
curl -H "Authorization: Bearer $ASTRAPP_API_KEY" https://app.astrapp.lat/api/v1/projects

# Incorrecto: "bearer" en minúsculas
curl -H "Authorization: bearer $ASTRAPP_API_KEY" https://app.astrapp.lat/api/v1/projects

Revisa el estado y la expiración de tus keys en Cuenta › API Keys.

404 o lista vacía con una key válida

Varias rutas leen los datos con la sesión de la app. Con una API Key no hay sesión, así que no encuentran nada y responden una lista vacía o un 404, aunque el recurso exista. Por ejemplo, GET /auth/api-keys devuelve [] y GET /projects/{projectId}/datasets responde Project not found.

Busca la ruta en Endpoints: si está marcada como “Solo sesión”, usa la alternativa que acepta API Key o hazlo desde la app.

Los scopes no causan errores

Hoy ninguna ruta revisa los scopes de una key, así que un 403 nunca se debe a que le falte un scope. Lee el mensaje del error: dice qué requisito falta o que el recurso no es tuyo.

Límite de peticiones

Un 429 con el código RATE_LIMIT_EXCEEDED significa que pasaste el tope de esa ruta. Espera lo que indica el header Retry-After y reintenta:

javascript

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let intento = 0; ; intento++) {
    const response = await fetch(url, options)
    if (response.status !== 429 || intento === maxRetries) return response

    // Retry-After viene en segundos; si falta, espera 1 s, 2 s, 4 s…
    const segundos = Number(response.headers.get('Retry-After')) || 2 ** intento
    await new Promise((resolve) => setTimeout(resolve, segundos * 1000))
  }
}

Los topes de cada ruta están en Endpoints.

Datasets

413 al subir un archivo

El cuerpo pasó de unos 4.5 MB y Vercel lo cortó antes de llegar a la ruta; por eso la respuesta no es JSON. Divide el archivo en partes más pequeñas.

400 Invalid ChatML schema at item N

Al crear un dataset con POST /datasets, el ejemplo N no es ChatML válido: revisa que messages tenga al menos un mensaje y que cada role sea system, user, assistant o tool. Para encontrar líneas con JSON mal formado en un archivo JSONL:

bash

python3 -c 'import json, sys
for n, linea in enumerate(open(sys.argv[1], encoding="utf-8"), 1):
    if linea.strip():
        try:
            json.loads(linea)
        except json.JSONDecodeError as e:
            print(f"Línea {n}: {e}")' conversaciones.jsonl

403 plan_limit_reached

Llegaste al máximo de datasets o de conversaciones de tu plan. Borra lo que ya no uses o sube de plan en Facturación. Los límites están en Planes y precios.

Entrenamiento

Mensajes de POST /gpu/instances/training y del entrenamiento en la GPU.

Mensaje	Qué hacer
Se requiere un nombre completo en tu perfil para rentar GPUs.	Completa tu nombre y tu teléfono en Configuración › Perfil, y confirma tu correo.
Saldo insuficiente para rentar esta GPU…	Recarga créditos en Facturación. Necesitas al menos el precio de una hora de la GPU.
Esta GPU no alcanza para el modelo elegido…	Elige una oferta con más VRAM o un modelo más pequeño.
Este modelo necesita al menos N GB de disco…	Sube diskSize al mínimo que indica el mensaje.
El modelo … no está en el catálogo de AstrApp.	Usa un modelo del catálogo con licencia Apache 2.0 o MIT.
Esta GPU ya no está disponible o su precio expiró…	El precio de la oferta venció (409). Busca ofertas otra vez y lanza de inmediato.
El dataset seleccionado no tiene conversaciones válidas para entrenar.	Revisa que el dataset tenga conversaciones en ChatML con mensajes de usuario y asistente.
GPU sin memoria suficiente (OOM).	Usa un modelo más pequeño o una GPU con más VRAM; bajar batchSize o maxSeqLength también reduce la memoria.

Tu entrenamiento falló a los 10 minutos sin hacer nada

Si el error es Job expiró sin respuesta (timeout automático) y lo lanzaste con POST /projects/{projectId}/training, esa ruta no entrena: solo crea un registro que nadie ejecuta. Usa POST /gpu/instances/training.

Inferencia

400 El modelo no está desplegado

Las rutas /inference/{modelId}/chat y /predict solo sirven modelos registrados en un proyecto con estado deployed. Para chatear desde tu código con una API Key usa POST /chat. Más en API de inferencia.

503 NOT_CONFIGURED en /chat

El proxy de modelos no está configurado en el servidor. No es un problema de tu petición: escribe a soporte.

Consejos generales

Guarda el request_id: los errores que pasan por el manejador común lo incluyen, y con él soporte encuentra tu petición en los registros.
No hay ambiente de pruebas: AstrApp tiene un solo entorno. Prueba con un proyecto y un dataset pequeños, no con una copia del entorno.
Registra tus peticiones: guarda requests y respuestas para depurar.

¿Necesitas más ayuda?

Escribe a [email protected] con el request_id del error.