Errores y límites

Comprender los errores de la API, los rate limits y las restricciones por plan.

Formato de respuesta de error

Todos los errores siguen un formato coherente:

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "error": true
}

Confía siempre en statusCode para el manejo programático y en statusMessage (o message) para el motivo legible. Los campos url y error son metadatos de conveniencia del framework subyacente.

Códigos de estado HTTP

2xx Éxito

4xx Errores del cliente

5xx Errores del servidor

Errores comunes

400 Bad Request

Campo requerido ausente:

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

Entrada no válida:

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}

401 Unauthorized

API key ausente:

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

Solución: incluye el header Authorization:

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

Límite de plan alcanzado:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Acceso denegado:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

El recurso no existe:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

415 Unsupported Media Type

Content-Type incorrecto:

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

Solución: usa el header Content-Type correcto:

• application/json para solicitudes JSON
• multipart/form-data para subidas de archivos

429 Too Many Requests

Rate limit superado:

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

Rate limits

La API v1 aplica una ventana fija por cuenta autenticada. El límite predeterminado del despliegue es de 300 solicitudes por minuto, pero puede configurarse. Lee siempre RateLimit-Limit y RateLimit-Remaining; tras un 429, espera los segundos indicados en Retry-After.

Límites del plan

Los distintos planes tienen distintos límites de recursos.

Límites de minds

Error cuando se alcanza el límite:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Límites de subida de knowledge

• Tamaño de archivo: máximo 50 MB por archivo (todos los planes)
• Almacenamiento: actualmente no se aplican límites explícitos de almacenamiento

Límites de API keys

• Máximo de keys: Actualmente no se aplica ningún límite.

Buenas prácticas

Manejo de errores

Maneja siempre los errores:

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

Lógica de reintentos

Implementa reintentos inteligentes:

• Reintenta con 429 (rate limit) y errores 5xx
• Usa backoff exponencial
• Establece un número máximo de reintentos
• No reintentes con errores 4xx (excepto 429)

Monitoreo

Controla tu uso:

• Registra los headers de rate limit
• Monitoriza las tasas de error
• Configura alertas para errores recurrentes
• Registra los tiempos de respuesta

Cuándo actualizar de plan

Actualiza tu plan si:

• Alcanzas rate limits con frecuencia
• Necesitas más minds
• Requieres subidas de archivos más grandes
• Quieres soporte prioritario

Ver planes

Obtener ayuda

Consultar el estado

Monitoriza el estado de nuestro servicio:

• Página de estado (próximamente)
• Sigue a @mindsai_co para novedades

Contactar con soporte

Si experimentas:

• Errores 500 persistentes
• Rate limiting incorrecto
• Comportamiento inesperado

Contáctanos:

• Formulario de feedback
• Email: [email protected]

Revisar la documentación

• Visión general de la API
• Autenticación
• Sparks API
• Knowledge API
• Chat API

Referencia de códigos de estado

Referencia rápida de todos los códigos de estado HTTP:

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable