API Fehler-Referenz

Dieser Leitfaden dokumentiert alle Fehlercodes, Antwortformate und Fehlerbehebungsschritte für die TeamDay API.

---

Fehler-Antwort-Format

Alle API-Fehler folgen einer konsistenten JSON-Struktur:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Detailed error description"
}

Felder:

• error (boolean) - Immer true für Fehler-Antworten
• statusCode (number) - HTTP Status Code
• statusMessage (string) - Menschenlesbarer Status
• message (string) - Detaillierte Fehler-Erklärung

---

HTTP Status Codes

2xx Erfolg

Dies sind keine Fehler, sondern erfolgreiche Antworten:

200 OK

Bedeutung: Anfrage erfolgreich

Verwendet von:

• GET Anfragen (auflisten, Details abrufen)
• PATCH Anfragen (aktualisieren)
• DELETE Anfragen (Soft Delete)
• POST Anfragen (Ausführung abbrechen)

201 Created

Bedeutung: Ressource erfolgreich erstellt

Verwendet von:

• POST Anfragen (Agent erstellen, Aufgabe erstellen)

---

4xx Client Fehler

Diese Fehler zeigen Probleme mit der Anfrage an.

400 Bad Request

Bedeutung: Ungültige Anfrage-Parameter oder fehlende erforderliche Felder

Häufige Ursachen:

• Fehlende erforderliche Felder
• Ungültige Feldwerte
• Malformed JSON
• Ungültige Query-Parameter

401 Unauthorized

Bedeutung: Authentifizierung erforderlich oder ungültig

Häufige Ursachen:

• Fehlendes oder abgelaufenes Token
• Ungültiges Token-Format
• Token nicht vorhanden

403 Forbidden

Bedeutung: Authentifiziert, aber keine Berechtigung

Häufige Ursachen:

• Benutzer hat keinen Zugriff auf diese Ressource
• Organisationsbeschränkung
• Rolle-basierte Zugriffskontrolle

404 Not Found

Bedeutung: Ressource nicht gefunden

Häufige Ursachen:

• Agent, Aufgabe oder Space existiert nicht
• Falsche Ressourcen-ID
• Ressource wurde gelöscht

429 Too Many Requests

Bedeutung: Rate Limit überschritten

Häufige Ursachen:

• Zu viele API Anfragen
• Kurzzeitig zu viele Anfragen

---

5xx Server Fehler

Diese Fehler zeigen Probleme auf der Server-Seite an.

500 Internal Server Error

Bedeutung: Unerwarteter Server-Fehler

503 Service Unavailable

Bedeutung: Server ist temporär nicht verfügbar

Häufige Ursachen:

• Wartungsarbeiten
• Hohe Last
• Temporärer Ausfall

---

Häufige Fehler und Lösungen

Fehlendes Token

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Missing or invalid authentication token"
}

Lösung:

1. Stellen Sie sicher, dass Sie ein gültiges Token haben
2. Verwenden Sie das richtige Header-Format: Authorization: Bearer YOUR_TOKEN
3. Überprüfen Sie, ob das Token abgelaufen ist

Abgelaufenes Token

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token has expired"
}

Lösung:

1. Generieren Sie ein neues Token in den Einstellungen
2. Aktualisieren Sie Ihre Umgebungsvariablen
3. Erneut versuchen

Rate Limit

{
  "error": true,
  "statusCode": 429,
  "statusMessage": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

Lösung:

1. Implementieren Sie Exponential Backoff
2. Warten Sie vor dem nächsten Versuch
3. Verwenden Sie Batch-Operationen, um Anfragen zu reduzieren