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": "Starter plan limit reached",
  "message": "Starter 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 Starter 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": "Starter plan limit reached",
  "message": "Starter 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.

Fallos de validación de audiencias

Iniciar una validación de audiencia en una audiencia con menos de 10 Minds listos devuelve 422 con el código AUDIENCE_TOO_SMALL. Una audiencia mayor de lo que tu plan permite en un estudio se rechaza con el error estándar de límite del plan descrito arriba.

Tras un inicio correcto, la validación se ejecuta en segundo plano, así que la mayoría de los fallos no son errores HTTP. Léelos en el campo failure del lote de validación. Un lote puede terminar con uno de estos códigos:

Buenas prácticas

Manejo de errores

Maneja siempre los errores:

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

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}

Lógica de reintentos

Implementa reintentos inteligentes:

• Reintenta las lecturas ante respuestas transitorias 429 o 5xx con retroceso exponencial limitado y respeta Retry-After. Reintenta escrituras solo cuando el endpoint documente idempotencia, conservando la misma clave y el mismo cuerpo. Tras un tiempo de espera ambiguo, comprueba el recurso o trabajo existente antes de volver a enviar.
• 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