Skip to content
Mähbarkeitsindex

Regeln, Rate Limits & Fehlercodes

Nutzungsregeln, Rate-Limiting-Verhalten und eine Referenz aller HTTP-Fehlercodes der Mähbarkeitsindex (MFI) API.

Rate Limiting

Rate Limiting

Die API begrenzt die Anfragenhäufigkeit pro API-Key. Das Standardlimit beträgt 1 Request pro 5 Minuten (300 Sekunden).

300 s

Standard-Intervall

429

HTTP-Status bei Überschreitung

pro Key

Zählung erfolgt je API-Key

Verhalten bei Überschreitung

Wird das Rate Limit überschritten, antwortet die API mit HTTP 429. Der Response-Header Retry-After enthält die Anzahl der Sekunden, nach der ein erneuter Request möglich ist.

HTTP-Response bei Rate-Limit-Überschreitung
HTTP/1.1 429 Too Many Requests
Retry-After: 187
Content-Type: application/json; charset=utf-8

{
  "status":  "error",
  "mfi":     null,
  "message": "Rate limit exceeded. Please wait 187 seconds before trying again."
}

Implementierungsempfehlung

Lies den Retry-After-Header aus und warte die angegebene Zeit ab, bevor du den Request wiederholst. Feste Wartezeiten können dazu führen, dass Requests unnötig lange warten oder weiterhin zu früh gesendet werden.

Temporäre Key-Sperrung bei ungewöhnlichem Verhalten

Über das reguläre Rate Limiting hinaus kann ein API-Key temporär gesperrt werden, wenn ungewöhnliche Nutzungsmuster erkannt werden. Dies erfolgt entweder automatisch durch das System oder manuell – etwa bei auffällig hohem Anfragevolumen, systematischen Fehlversuchen oder möglichem Missbrauch.

Sollte eine solche Sperrung andauern, unbeabsichtigt sein oder sollten anderweitig Probleme mit der API auftreten, ist eine Kontaktaufnahme jederzeit möglich.

Kontakt aufnehmen →

Retry-After auswerten – Codebeispiele

PHP – Retry-After auswerten
$ch = curl_init('https://api.maehbarkeitsindex.de/v1/calculate');
// ... curl_setopt ...
$response   = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpStatus === 429) {
    $data       = json_decode($response, true);
    // Retry-After aus Header lesen (bei curl_exec mit CURLOPT_HEADER)
    // oder aus eigenem Timing berechnen
    echo 'Rate limit. Bitte warten und erneut versuchen.';
}
JavaScript – Retry-After auswerten
const response = await fetch('https://api.maehbarkeitsindex.de/v1/calculate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer DEIN_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ temperature: 18.5, precipitation_rate: 0.0 }),
});

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  console.log(`Rate limit. Bitte ${retryAfter} Sekunden warten.`);
  return;
}

const data = await response.json();
API-Keys

API-Key-Regeln

Jeder API-Key hat individuelle Eigenschaften, die seinen Einsatzbereich und sein Verhalten steuern.

Erlaubte HTTP-Methoden

Standardmäßig sind API-Keys auf POST beschränkt. GET kann ausschließlich auf ausdrückliche Anfrage für Testzwecke freigeschaltet werden und ist nicht für den Produktionsbetrieb vorgesehen. Ein Request mit einer nicht erlaubten Methode wird mit HTTP 405 abgelehnt.

Aktivierungsstatus

Ein API-Key kann deaktiviert werden. Requests mit einem deaktivierten Key werden mit HTTP 403 und der Meldung API key is disabled. abgelehnt.

Rate-Limit-Intervall

Das Rate-Limit-Intervall kann pro Key individuell konfiguriert sein. Das Standard-Intervall beträgt 300 Sekunden.

IP-Blacklist

IP-Adressen können unabhängig vom API-Key gesperrt werden. Requests von gesperrten IP-Adressen werden sofort mit HTTP 403 und Access denied. abgelehnt – noch vor der Key-Prüfung.

Validierung

Verhalten bei ungültigen Eingaben

Die API unterscheidet zwischen zwei Arten von Eingabefehlern:

Pflichtfelder fehlen oder sind ungültig → HTTP 422

Wenn temperature oder precipitation_rate fehlen, nicht numerisch sind oder außerhalb des Gültigkeitsbereichs liegen, antwortet die API mit HTTP 422 und einer Fehlermeldung.

{
  "status":  "error",
  "mfi":     null,
  "message": "Required field 'temperature' is missing or contains an invalid value."
}

Optionale Felder außerhalb des Bereichs → Stilles Ignorieren

Optionale Parameter mit nicht-numerischen Werten oder Werten außerhalb des definierten Gültigkeitsbereichs werden ohne Fehler ignoriert. Das Feld gilt dann als nicht geliefert und erscheint in missing_fields der Antwort. Es wird kein HTTP-Fehler ausgegeben.

Fehlercodes

Vollständige HTTP-Fehlercode-Referenz

Alle möglichen HTTP-Statuscodes, die die MFI API zurückgeben kann, mit zugehöriger Fehlermeldung und Ursache.

Code message (englisch) Ursache
200 (leer) Erfolgreiche Berechnung
204 (kein Body) CORS Preflight: Antwort auf OPTIONS-Requests, kein JSON-Body
401 No API key provided. Kein API-Key im Request enthalten
401 Invalid API key. Übermittelter Key ist unbekannt oder falsch
403 Access denied. IP-Adresse ist auf der Blacklist
403 API key is disabled. Der verwendete API-Key wurde deaktiviert
404 Endpoint not found. URL-Pfad existiert nicht
404 API version vX is not available. Angeforderte API-Version existiert nicht oder ist deaktiviert
405 HTTP method not allowed. Verwendete HTTP-Methode ist für diesen API-Key nicht erlaubt
422 Required field '…' is missing or contains an invalid value. Pflichtfeld fehlt, ist nicht numerisch oder außerhalb des Bereichs
429 Rate limit exceeded. Please wait X seconds before trying again. Rate Limit überschritten. Retry-After-Header enthält Wartezeit in Sekunden.
500 Internal server error. Please try again later. Unerwarteter Serverfehler. Bitte später erneut versuchen.
503 The API is currently undergoing maintenance. Please try again later. Globaler Wartungsmodus ist aktiv
503 Database connection failed. Please try again later. Datenbankverbindung nicht verfügbar
CORS

CORS-Konfiguration

Die API sendet CORS-Header, die browserbasierte Requests aus beliebigen Herkunfts-Domains erlauben. Preflight-Requests (OPTIONS) werden mit HTTP 204 beantwortet.

Gesendete CORS-Header
Access-Control-Allow-Origin:  *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Hinweis zur clientseitigen Nutzung

Obwohl die API CORS zulässt, sollte der API-Key nicht im clientseitigen JavaScript-Code hinterlegt werden. Requests an die MFI API sollten stets über ein eigenes Backend-System erfolgen, das den Key schützt.

Fragen, Probleme oder Feedback?

Bei Fragen zur API, technischen Problemen, gefundenen Fehlern oder Verbesserungsvorschlägen – einfach Kontakt aufnehmen.

Kontakt aufnehmen →