---
title: "Errors & Limits"
description: "Verstehen Sie API-Fehler, Statuscodes und plan-basierte Ressourcenlimits."
---

# Errors & Limits

Verstehen Sie API-Fehler, Rate Limits und Plan-Einschränkungen.

## Error-Response-Format

Alle Fehler folgen einem einheitlichen Format:

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

<table>
<thead>
  <tr>
    <th>
      Feld
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        statusCode
      </code>
    </td>
    
    <td>
      HTTP status code
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        statusMessage
      </code>
    </td>
    
    <td>
      Menschenlesbare Fehlerbeschreibung (wird pro Fehler vom Handler gesetzt — bei Validierungsfehlern ist dies die konkrete Ursache, z. B. <code>
        "Mind not found"
      </code>
      
       oder <code>
        "Invalid Mind ID format"
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      Gleicher Inhalt wie <code>
        statusMessage
      </code>
      
       bei v1-Fehlern. In <code>
        5xx
      </code>
      
      -Responses von Debug-Builds reserviert für Stacktrace/Zusatzkontext.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      Der Request-Pfad (von Nuxt H3 hinzugefügt)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       bei Error-Responses (von Nuxt H3 hinzugefügt)
    </td>
  </tr>
</tbody>
</table>

> Verwenden Sie für die programmatische Verarbeitung stets `statusCode` und für die menschenlesbare Ursache `statusMessage` (oder `message`). Die Felder `url` und `error` sind Convenience-Metadaten des zugrundeliegenden Frameworks.

## HTTP Status Codes

### 2xx Success

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      200
    </td>
    
    <td>
      OK
    </td>
    
    <td>
      Request erfolgreich
    </td>
  </tr>
  
  <tr>
    <td>
      201
    </td>
    
    <td>
      Created
    </td>
    
    <td>
      Ressource erfolgreich erstellt (z. B. <code>
        POST /minds
      </code>
      
      , <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      Accepted
    </td>
    
    <td>
      Request zur asynchronen Verarbeitung angenommen (z. B. <code>
        POST /minds/{id}/knowledge
      </code>
      
       mit <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      No Content
    </td>
    
    <td>
      Request erfolgreich, kein Response-Body (z. B. <code>
        DELETE /minds/{id}/knowledge/{itemId}
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 4xx Client Errors

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      Bad Request
    </td>
    
    <td>
      Ungültige Request-Parameter
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      Unauthorized
    </td>
    
    <td>
      Fehlender oder ungültiger API key
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      Forbidden
    </td>
    
    <td>
      Zugriff verweigert oder Plan-Limit erreicht
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      Not Found
    </td>
    
    <td>
      Ressource existiert nicht
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      Unsupported Media Type
    </td>
    
    <td>
      Falscher Content-Type-Header
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      Too Many Requests
    </td>
    
    <td>
      Rate limit überschritten
    </td>
  </tr>
</tbody>
</table>

### 5xx Server Errors

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Beschreibung
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      Internal Server Error
    </td>
    
    <td>
      Serverseitiger Fehler
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      Service Unavailable
    </td>
    
    <td>
      Dienst vorübergehend nicht verfügbar
    </td>
  </tr>
</tbody>
</table>

## Häufige Fehler

### 400 Bad Request

**Fehlendes Pflichtfeld:**

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

**Ungültige Eingabe:**

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

### 401 Unauthorized

**Fehlender API key:**

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

**Lösung:** Fügen Sie den `Authorization`-Header ein:

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

### 403 Forbidden

**Plan-Limit erreicht:**

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

**Zugriff verweigert:**

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

### 404 Not Found

**Ressource existiert nicht:**

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

### 415 Unsupported Media Type

**Falscher Content-Type:**

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

**Lösung:** Verwenden Sie den korrekten `Content-Type`-Header:

- `application/json` für JSON-Requests
- `multipart/form-data` für Datei-Uploads

### 429 Too Many Requests

**Rate limit überschritten:**

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

## Rate Limits

Die v1 API erzwingt ein festes Zeitfenster pro authentifiziertem Konto. Das Deployment-Standardlimit beträgt 300 Requests pro Minute, ist aber konfigurierbar. Lesen Sie deshalb immer `RateLimit-Limit` und `RateLimit-Remaining`; nach `429` warten Sie die in `Retry-After` angegebenen Sekunden.

## Plan-Limits

Die aktuellen öffentlichen Standardwerte finden Sie in der generierten [Plan-Limit-Tabelle](/docs/api/overview). Vertragliche Overrides können abweichen; bei einem authentifizierten Fehler sind deshalb `data.limit` und `data.current` für die jeweilige Anfrage maßgeblich. Der Individual-Plan wird in API-Payloads als `"premium"` ausgegeben.

### Beispiel für ein Mind-Limit

**Fehler bei erreichtem Limit:**

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

### Knowledge-Upload-Limits

- **Dateigröße:** Maximal 50MB pro Datei (alle Pläne)
- **Speicher:** Derzeit keine expliziten Speicherlimits erzwungen

### API-Key-Limits

- **Maximale Keys:** Derzeit wird keine Obergrenze erzwungen.

## Best Practices

### Fehlerbehandlung

**Behandeln Sie Fehler stets:**

```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);
}
```

### Retry-Logik

**Implementieren Sie intelligente Retries:**

- Bei `429` (Rate limit) und `5xx`-Fehlern wiederholen
- Exponential Backoff verwenden
- Maximale Retry-Anzahl festlegen
- Keine Retries bei `4xx`-Fehlern (außer 429)

### Monitoring

**Überwachen Sie Ihre Nutzung:**

- Rate-Limit-Header protokollieren
- Fehlerraten überwachen
- Alerts für wiederkehrende Fehler einrichten
- Response-Zeiten tracken

### Upgraden, wenn nötig

Upgraden Sie Ihren Plan, wenn Sie:

- häufig Rate Limits erreichen
- mehr Minds benötigen
- größere Datei-Uploads benötigen
- Priority Support wünschen

[Pläne ansehen](/settings?tab=subscription)

## Hilfe erhalten

### Status prüfen

Überwachen Sie den Status unseres Dienstes:

- [Minds-Dienststatus](https://uptime.getminds.ai)
- Folgen Sie [@mindsai_co](https://x.com/mindsai_co) für Updates

### Support kontaktieren

Falls bei Ihnen Folgendes auftritt:

- Dauerhafte 500-Fehler
- Fehlerhaftes Rate Limiting
- Unerwartetes Verhalten

Kontaktieren Sie uns:

- Feedback-Formular
- E-Mail: [support@getminds.ai](mailto:support@getminds.ai)

### Dokumentation durchsehen

- [API-Übersicht](/docs/api/overview)
- [Authentifizierung](/docs/api/authentication)
- [Minds API](/docs/api/minds)
- [Knowledge API](/docs/api/knowledge)
- [Chat API](/docs/api/chat)

## Status Codes – Referenz

Schnellreferenz für alle HTTP status codes:

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