> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastino.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Use https://docs.fastino.ai/llms.txt to discover and navigate pages. Use https://docs.fastino.ai/llms-full.txt when you need the complete documentation corpus. Use https://docs.fastino.ai/openapi.json as the source of truth for customer-facing routes. For GLiDE decision inference, call POST https://api.fastino.ai/v1/systemone with model fastino/GLiDE. Do not infer undocumented routes. Read API keys from FASTINO_API_KEY and never embed credentials in code, logs, or reports.
# Errores y formatos de respuesta de la API de Fastino
> Todos los códigos 4xx y 5xx que devuelve la API de Fastino, el formato JSON por familia y los pasos para resolver errores de facturación, límites y validación.
La API de Fastino utiliza códigos de estado HTTP estándar para comunicar el resultado de cada solicitud. Los códigos en el rango `2xx` indican éxito. Los códigos en el rango `4xx` indican un problema con tu solicitud que puedes corregir. Los códigos en el rango `5xx` indican un problema del lado del servidor.
## Formato de la respuesta de error
La mayoría de las respuestas de error devuelven un cuerpo JSON con un campo `detail`:
```json theme={null}
{
"detail": "..."
}
```
Algunas familias de respuestas usan una forma diferente:
* **Denegaciones de facturación** (`402`, algunos `403`) devuelven `{"code", "message", "resolution_url"}` en lugar de `detail` - consulta [402](#402-pago-requerido) y [403](#403-prohibido) más abajo.
* **Respuestas de calentamiento** (`425`) incluyen un encabezado `Retry-After`. Los cuerpos con forma de OpenAI también llevan `code: "model_warming"` - consulta [425](#425-demasiado-pronto) más abajo.
* **Respuestas de límite de velocidad** (`429`) añaden los campos `code` y `scope` junto a `detail`, además de los encabezados `X-RateLimit-Scope` y `X-RateLimit-Code` - consulta [429](#429-demasiadas-solicitudes) más abajo.
* **Errores del servidor no controlados** (`500`) devuelven `{"error", "message"}` en lugar de `detail`.
* Las solicitudes a los endpoints compatibles con OpenAI (`/v1/chat/completions`, `/v1/responses`) reciben una envoltura con forma de OpenAI `{"error": {"code", "type", "param", "message"}}`, y las solicitudes que llevan un encabezado `anthropic-version` reciben una envoltura con forma de Anthropic `{"type": "error", "error": {"type", "message"}}` en lugar de las formas genéricas anteriores.
## Códigos de estado
### 400 - Solicitud incorrecta
La solicitud en sí está mal formada - JSON no válido, o un parámetro de consulta/ruta con un tipo incorrecto.
**Cómo solucionarlo:** Confirma que el cuerpo de tu solicitud sea JSON válido y que los parámetros de consulta/ruta coincidan con los tipos documentados en la referencia del endpoint.
***
### 401 - No autorizado
Tu solicitud no incluyó una clave de API válida, la clave ha sido revocada, o tu cuenta ha sido bloqueada por revisión de facturación o fraude.
**Cómo solucionarlo:** Verifica que el encabezado `X-API-Key` esté presente y contenga tu clave actual. Si revocaste la clave recientemente, genera una nueva en **Settings** → **API Keys**. Si tu cuenta está bloqueada, contacta a [support@pioneer.ai](mailto:support@pioneer.ai). Consulta [Autenticación](/es/authentication) para instrucciones de configuración.
***
### 402 - Pago requerido
Una respuesta `402` significa que tu cuenta se ha quedado sin créditos utilizables o que se requiere una acción de facturación antes de poder ejecutar inferencia. Todas las llamadas a la API fallarán hasta que añadas créditos o mejores tu plan. Visita **Settings** → **Billing** o consulta [Planes y precios](/es/pricing) para resolverlo.
Tu cuenta no tiene créditos suficientes para completar la solicitud. El campo `code` del cuerpo de la respuesta te indica qué caso se aplica - normalmente `out_of_credits` (tus créditos incluidos están agotados y no hay saldo pagado utilizable) o `direct_model_requires_credits` (llamar directamente a un modelo compatible requiere un saldo de créditos pagados).
**Cómo solucionarlo:** Inicia sesión en [Fastino](https://agent.fastino.ai), ve a **Settings** → **Billing** y recarga tu saldo o mejora tu plan. Consulta [Límites de créditos y tope de gasto por excedente](/es/api-reference/rate-limits#límites-de-créditos-y-tope-de-gasto-por-excedente) para conocer cómo funcionan los límites de créditos y la facturación por excedente.
***
### 403 - Prohibido
Tu equipo ha alcanzado el gasto máximo mensual por excedente de su plan (`code: "credit_ceiling_reached"`), o tu cuenta necesita un método de pago verificado antes de ejecutar inferencia (`code: "card_required"`).
**Cómo solucionarlo:** Para una denegación por tope de gasto, mejora tu plan en **Settings** → **Billing** para aumentar el tope. Para una denegación por verificación de tarjeta, añade un método de pago válido. Ambas respuestas incluyen un `resolution_url` que apunta directamente a la página para resolverlas.
***
### 404 - No encontrado
El recurso que solicitaste no existe. Esto puede ocurrir cuando el nombre de un dataset, un ID de trabajo de entrenamiento, un ID de evaluación, un ID de proyecto o un ID de modelo está mal escrito o ha sido eliminado.
**Cómo solucionarlo:** Verifica dos veces el ID o el nombre en la ruta o el cuerpo de la solicitud. Usa el endpoint `GET` de listado correspondiente (por ejemplo `GET /v1/training-jobs`, `GET /v1/base-models`) para confirmar que el recurso existe.
***
### 409 - Conflicto
El modelo existe en el catálogo pero no puede servirse actualmente - por ejemplo, un modelo base solo para entrenamiento solicitado para inferencia directa, o un despliegue on-demand que no ha terminado de aprovisionarse después de completarse un trabajo de entrenamiento.
**Cómo solucionarlo:** Consulta `supports_inference` y `supports_on_demand_inference` para el modelo a través de `GET /v1/base-models`, o reintenta después de que el despliegue termine de aprovisionarse.
***
### 413 - Carga útil demasiado grande
El cuerpo de la solicitud - normalmente una carga de archivo para una evaluación o dataset - excede el límite de tamaño del endpoint.
**Cómo solucionarlo:** Revisa la referencia del endpoint para conocer su límite de tamaño de carga y divide o comprime la carga útil antes de reintentar.
***
### 422 - Entidad no procesable
El cuerpo de la solicitud no superó la validación. Falta un campo obligatorio, un campo tiene el tipo incorrecto, o un valor está fuera del rango aceptado.
**Cómo solucionarlo:** Revisa el `message` del error para identificar el campo específico que falló. Las causas comunes incluyen:
* Omitir `base_model` en `POST /v1/training-jobs`
* Enviar menos de 1 o más de 1.000 cadenas en el arreglo `inputs` para endpoints de etiquetas existentes
```json theme={null}
{
"detail": "For 'POST /v1/training-jobs', ...",
"errors": [...]
}
```
***
### 425 - Demasiado pronto
El modelo se está calentando temporalmente y aún no está listo para servir inferencia. Esto es esperable en la primera solicitud tras un periodo sin tráfico o contra un despliegue on-demand recién aprovisionado, y no significa que tu solicitud sea incorrecta. El tiempo de calentamiento depende del modelo, así que una solicitud puede devolver `425` más de una vez antes de tener éxito.
La mayoría de los endpoints devuelven un cuerpo con forma de OpenAI con `code: "model_warming"`:
```json theme={null}
{
"error": {
"message": "...",
"type": "invalid_request_error",
"param": null,
"code": "model_warming"
}
}
```
Las solicitudes a `/v1/messages` que llevan un encabezado `anthropic-version` reciben en su lugar un cuerpo con forma de Anthropic, sin campo `code`:
```json theme={null}
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "..."
}
}
```
| Encabezado | Valor |
| - | - |
| `Retry-After` | Segundos que hay que esperar antes del siguiente intento. Es un retardo de reintento, no una promesa de que el modelo estará listo. |
| `x-should-retry` | `true` en las respuestas con forma de OpenAI, por lo que los SDK de OpenAI reintentan automáticamente. `false` en las respuestas con forma de Anthropic, por lo que los SDK de Anthropic no reintentan; gestiónalas tú mismo. |
**Cómo solucionarlo:** Espera `Retry-After` segundos (30 si falta el encabezado) y vuelve a enviar la misma solicitud, con un número limitado de reintentos. Cada ejemplo reintenta como máximo 5 veces, establece un tiempo de espera del cliente de 300 segundos y se detiene ante cualquier otra respuesta que no sea 2xx. El mismo bucle sirve para `/v1/systemone`; cambia la URL y el cuerpo de la solicitud.
```bash cURL theme={null}
for attempt in 0 1 2 3 4 5; do
http_code=$(curl -sS --max-time 300 -o response.json -D headers.txt -w "%{http_code}" \
https://api.fastino.ai/v1/chat/completions \
-H "Authorization: Bearer $FASTINO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fastino/gliner2.5-multi-v1",
"messages": [{ "role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino." }],
"schema": { "entities": ["organization", "product"] }
}')
[ "$http_code" = "425" ] && [ "$attempt" -lt 5 ] || break
delay=$(awk 'tolower($1) == "retry-after:" && $2 + 0 > 0 { print $2 + 0 }' headers.txt)
sleep "${delay:-30}"
done
if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
cat response.json
else
echo "Request failed with HTTP $http_code: $(cat response.json)" >&2
fi
```
```python Python theme={null}
import os
import time
import requests
MAX_RETRIES = 5
for attempt in range(MAX_RETRIES + 1):
response = requests.post(
"https://api.fastino.ai/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['FASTINO_API_KEY']}"},
json={
"model": "fastino/gliner2.5-multi-v1",
"messages": [
{"role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino."}
],
"schema": {"entities": ["organization", "product"]},
},
timeout=300,
)
if response.status_code != 425 or attempt == MAX_RETRIES:
break
retry_after = response.headers.get("Retry-After", "")
time.sleep(int(retry_after) if retry_after.isdigit() else 30)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"Request failed: {response.status_code} {response.text}")
print(response.json()["choices"][0]["message"]["content"])
```
```javascript JavaScript theme={null}
const MAX_RETRIES = 5;
let response;
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
response = await fetch("https://api.fastino.ai/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FASTINO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "fastino/gliner2.5-multi-v1",
messages: [{ role: "user", content: "Apple announced the MacBook Pro at WWDC in Cupertino." }],
schema: { entities: ["organization", "product"] },
}),
signal: AbortSignal.timeout(300_000),
});
if (response.status !== 425 || attempt === MAX_RETRIES) break;
const retryAfter = Number(response.headers.get("Retry-After"));
await new Promise((resolve) => setTimeout(resolve, (retryAfter || 30) * 1000));
}
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${await response.text()}`);
}
const completion = await response.json();
console.log(completion.choices[0].message.content);
```
Con un SDK, consulta [Reintentos y calentamiento de modelos](/es/troubleshooting/retries) para saber qué respuestas reintentar y cómo aplicar backoff.
***
### 429 - Demasiadas solicitudes
Has superado un límite de velocidad de solicitudes para este endpoint. La respuesta incluye un encabezado `Retry-After`, además de los encabezados `X-RateLimit-Scope` y `X-RateLimit-Code` que identifican qué límite alcanzaste - el cuerpo JSON contiene los campos `code` y `scope` correspondientes junto a `detail`.
**Cómo solucionarlo:** Respeta el valor de `Retry-After` y espera antes de reintentar. Consulta [Límites de velocidad](/es/api-reference/rate-limits) para conocer los límites por endpoint y un patrón de código de reintento. Ten en cuenta que las denegaciones por créditos y por excedente devuelven `402`/`403`, no `429` - consulta [Límites de créditos y tope de gasto por excedente](/es/api-reference/rate-limits#límites-de-créditos-y-tope-de-gasto-por-excedente).
***
### 451 - No disponible por motivos legales
El modelo solicitado no está disponible para tu cuenta debido a restricciones de control de exportaciones o sanciones en tu región.
**Cómo solucionarlo:** Consulta las [Preguntas frecuentes](/es/faq) para ver la lista actual de regiones restringidas y las políticas específicas de cada proveedor. Si crees que tu acceso fue restringido incorrectamente, contacta con soporte.
***
### 500 - Error interno del servidor
Ocurrió un error inesperado en los servidores de Fastino. Esto no es causado por tu solicitud. El cuerpo usa los campos `error` y `message` en lugar de `detail`:
```json theme={null}
{
"error": "Internal server error",
"message": "..."
}
```
**Cómo solucionarlo:** Espera un momento y reintenta. Si el error persiste, consulta [status.pioneer.ai](https://status.pioneer.ai) para ver el estado del servicio en vivo o contacta con soporte.
***
### 503 - Servicio no disponible
Una dependencia que la solicitud necesitaba - verificación de facturación, o un endpoint de estado/métricas de un proveedor - está temporalmente no disponible.
**Cómo solucionarlo:** Espera un momento y reintenta. Si el error persiste, consulta [status.pioneer.ai](https://status.pioneer.ai) para ver el estado del servicio en vivo o contacta con soporte.
***
### 529 - Sobrecargado (solo endpoint compatible con Anthropic)
`POST /v1/messages` replica la propia respuesta `overloaded_error` de Anthropic cuando la capacidad ascendente de Claude está temporalmente saturada.
**Cómo solucionarlo:** Reintenta con backoff, igual que harías para un `429` o `503`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.