Fehlerbehandlung

Die MILKEE API verwendet standardisierte HTTP-Status-Codes und gibt strukturierte Fehlermeldungen im JSON-Format zurück.

HTTP-Status-Codes

Erfolgreiche Antworten (2xx)

Code	Bedeutung	Beschreibung
200	OK	Request erfolgreich
201	Created	Ressource erfolgreich erstellt
204	No Content	Request erfolgreich, keine Daten zurückgegeben

Client-Fehler (4xx)

Code	Bedeutung	Beschreibung
400	Bad Request	Ungültige Request-Syntax
401	Unauthorized	Authentifizierung fehlgeschlagen
402	Payment Required	Abonnement abgelaufen
403	Forbidden	Keine Berechtigung für diese Aktion
404	Not Found	Ressource nicht gefunden
422	Unprocessable Entity	Validation fehlgeschlagen
429	Too Many Requests	Rate Limit überschritten

Server-Fehler (5xx)

Code	Bedeutung	Beschreibung
500	Internal Server Error	Unerwarteter Server-Fehler
503	Service Unavailable	Service temporär nicht verfügbar

Fehler-Response-Format

Standard-Fehlerformat

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "Specific error message"
    ]
  }
}

Beispiele

401 Unauthorized

{
  "message": "Unauthenticated."
}

402 Payment Required

{
  "message": "Dein Abo ist abgelaufen."
}

404 Not Found

{
  "message": "No query results for model [App\\Models\\Tag] 999"
}

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "color": [
      "The selected color is invalid."
    ]
  }
}

Validation-Fehler

Bei Validation-Fehlern (422) enthält das errors-Objekt spezifische Feldnamen als Schlüssel und Arrays mit Fehlermeldungen als Werte.

Häufige Validation-Fehler

Tags API

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required.",
      "The name has already been taken."
    ],
    "color": [
      "The selected color is invalid."
    ]
  }
}

Mögliche name-Fehler:

• required: Name ist erforderlich
• max:255: Name zu lang (max. 255 Zeichen)
• unique: Name bereits in dieser Firma vorhanden

Mögliche color-Fehler:

• required: Farbe ist erforderlich
• invalid: Ungültige Farbe (siehe verfügbare Farben)

Fehlerbehandlung in Code

JavaScript/Fetch

async function createTag(companyId, tagData) {
  try {
    const response = await fetch(`/api/v2/companies/${companyId}/tags`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tagData)
    });

    if (!response.ok) {
      const error = await response.json();
      
      if (response.status === 422) {
        // Validation errors
        console.error('Validation errors:', error.errors);
      } else if (response.status === 401) {
        // Authentication error
        console.error('Authentication failed');
      } else if (response.status === 402) {
        // Subscription error
        console.error('Subscription expired');
      }
      
      throw new Error(error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

PHP/cURL

<?php

function createTag($companyId, $tagData, $token) {
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_URL, "https://app.milkee.ch/api/v2/companies/{$companyId}/tags");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($tagData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    if ($httpCode >= 400) {
        switch ($httpCode) {
            case 401:
                throw new Exception('Authentication failed');
            case 402:
                throw new Exception('Subscription expired');
            case 422:
                $errors = $data['errors'] ?? [];
                throw new Exception('Validation failed: ' . implode(', ', array_flatten($errors)));
            default:
                throw new Exception($data['message'] ?? 'API Error');
        }
    }
    
    return $data;
}

Debugging-Tipps

Request-Debugging

1. Status-Code prüfen: Beginnen Sie immer mit dem HTTP-Status-Code
2. Headers prüfen: Stellen Sie sicher, dass Authorization und Content-Type korrekt sind
3. Request-Body prüfen: Validieren Sie JSON-Format und erforderliche Felder
4. URL prüfen: Stellen Sie sicher, dass Firmen-ID und Endpoint korrekt sind

Response-Debugging

1. Vollständige Response loggen: Loggen Sie sowohl Status als auch Body
2. Validation-Errors analysieren: Bei 422-Fehlern alle Feld-Fehler durchgehen
3. Rate-Limiting beachten: Bei 429-Fehlern Pause einlegen

Häufige Probleme

"Unauthenticated" trotz Token

• Token-Format prüfen: Muss Bearer (mit Leerzeichen) vorangestellt werden
• Token-Gültigkeit prüfen: Token in MILKEE-Einstellungen überprüfen
• HTTPS verwenden: API funktioniert nur über HTTPS

"No query results for model"

• Ressourcen-ID prüfen: Existiert die angeforderte Ressource?
• Firmen-Zugriff prüfen: Gehört die Ressource zur angegebenen Firma?
• Berechtigungen prüfen: Hat der Token-Benutzer Zugriff?

"Dein Abo ist abgelaufen"

• Abonnement erneuern: Business Plan in MILKEE-Einstellungen erneuern
• Zahlungsmethode prüfen: Ist die Zahlungsmethode gültig?

Nächste Schritte

• Rate Limiting verstehen
• Tags API ausprobieren
• Code-Beispiele ansehen