Fehlerbehandlung¶

Alle API-Fehler folgen einem einheitlichen JSON-Format. Jede Fehlerantwort enthält eine eindeutige Fehler-ID, einen maschinenlesbaren Fehlercode, eine menschenlesbare Nachricht und ein details-Array für feldspezifische Validierungsfehler.

Fehlerstruktur¶

{
  "error_id": "err_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "error_code": "ENTITY_NOT_FOUND",
  "message": "PlantInstance with key 'pi_xyz' not found.",
  "details": [
    {
      "field": "key",
      "reason": "No PlantInstance with key 'pi_xyz'.",
      "code": "ENTITY_NOT_FOUND"
    }
  ],
  "timestamp": "2026-03-17T10:30:00.000000+00:00",
  "path": "/api/v1/plant-instances/pi_xyz",
  "method": "GET"
}

HTTP-Statuscodes¶

Fehlercodes¶

Allgemeine Fehler¶

Authentifizierungs- und Autorisierungsfehler¶

Phasen- und Statusfehler¶

Pflanzenschutz- und Erntefehler¶

Substrat- und Kompatibilitätsfehler¶

Externe Dienste¶

Validierungsfehler (422)¶

FastAPI und Pydantic erzeugen bei Eingabefehler automatisch strukturierte Validierungsfehler. Die details-Liste enthält für jedes fehlerhafte Feld einen eigenen Eintrag:

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "kein-gueltige-email",
  "password": "kurz",
  "display_name": ""
}

Antwort (422):

{
  "error_id": "err_b5e3c8a1-...",
  "error_code": "VALIDATION_ERROR",
  "message": "The input data is invalid.",
  "details": [
    {
      "field": "body.email",
      "reason": "value is not a valid email address",
      "code": "value_error"
    },
    {
      "field": "body.password",
      "reason": "String should have at least 10 characters",
      "code": "string_too_short"
    },
    {
      "field": "body.display_name",
      "reason": "String should have at least 1 character",
      "code": "string_too_short"
    }
  ],
  "timestamp": "2026-03-17T10:30:00.000000+00:00",
  "path": "/api/v1/auth/register",
  "method": "POST"
}

Karenz-Violation (KARENZ_VIOLATION)¶

Der Karenz-Gate-Mechanismus verhindert die Erstellung einer Ernte, solange die Karenzzeit eines angewendeten Pflanzenschutzmittels noch nicht abgelaufen ist.

POST /api/v1/t/mein-garten/harvest/batches

Antwort (422), wenn Karenzzeit aktiv:

{
  "error_id": "err_c7d2e5f3-...",
  "error_code": "KARENZ_VIOLATION",
  "message": "Cannot harvest: safety interval for 'Pyrethrin' has 5 days remaining.",
  "details": [
    {
      "field": "active_ingredient",
      "reason": "Safety interval not elapsed: 5 days remaining.",
      "code": "KARENZ_VIOLATION"
    }
  ],
  "timestamp": "2026-03-17T10:30:00.000000+00:00",
  "path": "/api/v1/t/mein-garten/harvest/batches",
  "method": "POST"
}

Konflikte (409)¶

HTTP 409 wird verwendet, wenn eine Operation aufgrund des aktuellen Zustands nicht durchführbar ist — etwa das Hinzufügen einer Pflanze zu einem bereits abgeschlossenen Durchlauf:

{
  "error_id": "err_a1b2c3d4-...",
  "error_code": "INVALID_RUN_STATE",
  "message": "Operation 'add_plant' not allowed in status 'completed'.",
  "details": [],
  "timestamp": "2026-03-17T10:30:00.000000+00:00",
  "path": "/api/v1/t/mein-garten/planting-runs/run_123/plants",
  "method": "POST"
}

Rate Limiting (429)¶

Bei Überschreitung des Rate Limits antwortet die API mit HTTP 429. Der Retry-After-Header gibt an, nach wie vielen Sekunden ein erneuter Versuch möglich ist:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded: 20 per 1 minute"
}

Interne Fehler (500)¶

Bei unerwarteten internen Fehlern gibt die API niemals Details über die serverseitige Ursache preis. Die error_id ist das einzige Instrument zur Fehlerkorrelation:

{
  "error_id": "err_9f8e7d6c-...",
  "error_code": "INTERNAL_ERROR",
  "message": "An internal error occurred. Please contact support with the reference ID.",
  "details": [],
  "timestamp": "2026-03-17T10:30:00.000000+00:00",
  "path": "/api/v1/t/mein-garten/plant-instances/",
  "method": "GET"
}

Empfehlungen für API-Clients¶

• Fehlercode auswerten, nicht nur den HTTP-Statuscode. Mehrere semantisch unterschiedliche Fehler können denselben Statuscode haben (z.B. sind KARENZ_VIOLATION, HST_VIOLATION und ROTATION_VIOLATION alle HTTP 422).
• error_id protokollieren. In eigenen Logs und bei Support-Anfragen immer die error_id angeben.
• details-Array iterieren für feldspezifische Fehlermeldungen in Formularvalidierungen.
• Auf 401 mit Token-Refresh reagieren. Nach Ablauf des Access Tokens (15 min) liefert die API 401 UNAUTHORIZED. Der Client soll automatisch einen Refresh-Versuch starten.
• 409 INVALID_RUN_STATE nicht wiederholen. Dieser Fehler zeigt einen fachlichen Zustandskonflikt an — die Operation ist erst nach einer Zustandsänderung möglich.

Siehe auch¶

• API-Überblick — URL-Struktur und Endpunkt-Gruppen
• Authentifizierung — Auth-Fehler im Detail
• IPM-System — Karenzzeit-Konzept erklärt