---
title: "Errores y límites"
description: "Comprender los errores de la API, los códigos de estado y los límites de recursos según el plan."
---

# 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:

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

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        statusCode
      </code>
    </td>
    
    <td>
      Código de estado HTTP
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        statusMessage
      </code>
    </td>
    
    <td>
      Descripción del error legible para humanos (configurada por cada handler — para errores de validación es el problema específico, p. ej. <code>
        "Mind not found"
      </code>
      
       o <code>
        "Invalid Mind ID format"
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      Mismo contenido que <code>
        statusMessage
      </code>
      
       para errores v1. Reservado para contexto de stack o información adicional en respuestas <code>
        5xx
      </code>
      
       en builds de debug.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      La ruta de la solicitud (añadida por Nuxt H3)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       para respuestas de error (añadido por Nuxt H3)
    </td>
  </tr>
</tbody>
</table>

> 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

<table>
<thead>
  <tr>
    <th>
      Código
    </th>
    
    <th>
      Estado
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      200
    </td>
    
    <td>
      OK
    </td>
    
    <td>
      La solicitud se completó correctamente
    </td>
  </tr>
  
  <tr>
    <td>
      201
    </td>
    
    <td>
      Created
    </td>
    
    <td>
      Recurso creado correctamente (p. ej. <code>
        POST /minds
      </code>
      
      , <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      Accepted
    </td>
    
    <td>
      Solicitud aceptada para procesamiento asíncrono (p. ej. <code>
        POST /minds/{id}/knowledge
      </code>
      
       con <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      No Content
    </td>
    
    <td>
      La solicitud se completó, sin body en la respuesta (p. ej. <code>
        DELETE /minds/{id}/knowledge/{itemId}
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 4xx Errores del cliente

<table>
<thead>
  <tr>
    <th>
      Código
    </th>
    
    <th>
      Estado
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      Bad Request
    </td>
    
    <td>
      Parámetros de solicitud no válidos
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      Unauthorized
    </td>
    
    <td>
      API key ausente o no válida
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      Forbidden
    </td>
    
    <td>
      Acceso denegado o límite de plan alcanzado
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      Not Found
    </td>
    
    <td>
      El recurso no existe
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      Unsupported Media Type
    </td>
    
    <td>
      Header Content-Type incorrecto
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      Too Many Requests
    </td>
    
    <td>
      Rate limit superado
    </td>
  </tr>
</tbody>
</table>

### 5xx Errores del servidor

<table>
<thead>
  <tr>
    <th>
      Código
    </th>
    
    <th>
      Estado
    </th>
    
    <th>
      Descripción
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      Internal Server Error
    </td>
    
    <td>
      Error del lado del servidor
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      Service Unavailable
    </td>
    
    <td>
      Servicio no disponible temporalmente
    </td>
  </tr>
</tbody>
</table>

## Errores comunes

### 400 Bad Request

**Campo requerido ausente:**

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

**Entrada no válida:**

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

### 401 Unauthorized

**API key ausente:**

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

**Solución:** incluye el header `Authorization`:

```bash
-H "Authorization: Bearer minds_your_api_key"
```

### 403 Forbidden

**Límite de plan alcanzado:**

```json
{
  "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:**

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

### 404 Not Found

**El recurso no existe:**

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

### 415 Unsupported Media Type

**Content-Type incorrecto:**

```json
{
  "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:**

```json
{
  "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](/docs/api/overview) 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:**

```json
{
  "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:**

```javascript
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](/settings?tab=subscription)

## Obtener ayuda

### Consultar el estado

Monitoriza el estado de nuestro servicio:

- [Estado del servicio de Minds](https://uptime.getminds.ai)
- Sigue a [@mindsai_co](https://x.com/mindsai_co) para novedades

### Contactar con soporte

Si experimentas:

- Errores 500 persistentes
- Rate limiting incorrecto
- Comportamiento inesperado

Contáctanos:

- Formulario de feedback
- Email: [support@getminds.ai](mailto:support@getminds.ai)

### Revisar la documentación

- [Visión general de la API](/docs/api/overview)
- [Autenticación](/docs/api/authentication)
- [Minds API](/docs/api/minds)
- [Knowledge API](/docs/api/knowledge)
- [Chat API](/docs/api/chat)

## Referencia de códigos de estado

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

```text
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
```