Errors & Limits

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

Error-Response-Format

Alle Fehler folgen einem einheitlichen Format:

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

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

4xx Client Errors

5xx Server Errors

Häufige Fehler

400 Bad Request

Fehlendes Pflichtfeld:

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

Ungültige Eingabe:

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

401 Unauthorized

Fehlender API key:

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

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

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

Plan-Limit erreicht:

{
  "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
  }
}

Zugriff verweigert:

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

404 Not Found

Ressource existiert nicht:

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

415 Unsupported Media Type

Falscher Content-Type:

{
  "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:

{
  "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

Unterschiedliche Pläne haben unterschiedliche Ressourcenlimits.

Mind-Limits

Fehler bei erreichtem Limit:

{
  "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
  }
}

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:

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

Hilfe erhalten

Status prüfen

Überwachen Sie den Status unseres Dienstes:

• Status-Seite (folgt in Kürze)
• Folgen Sie @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: [email protected]

Dokumentation durchsehen

• API-Übersicht
• Authentifizierung
• Sparks API
• Knowledge API
• Chat API

Status Codes – Referenz

Schnellreferenz für alle HTTP status codes:

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