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/minds",
  "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/minds",
  "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": "Mind 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

Consulta la tabla de límites generada para ver los valores públicos actuales. Las excepciones contractuales pueden variar; por ello, data.limit y data.current en un error autenticado son los valores autoritativos para esa solicitud. El plan Individual aparece como "premium" en los payloads de la API.

Ejemplo de límite de Minds

Error cuando se alcanza el límite:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/minds",
  "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:

• Estado del servicio de Minds
• 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
• Minds 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