Regeln, Rate Limits & Fehlercodes
Nutzungsregeln, Rate-Limiting-Verhalten und eine Referenz aller HTTP-Fehlercodes der Mähbarkeitsindex (MFI) API.
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/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
$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.';
}
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-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.
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.
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-Konfiguration
Die API sendet CORS-Header, die browserbasierte Requests aus beliebigen Herkunfts-Domains erlauben. Preflight-Requests (OPTIONS) werden mit HTTP 204 beantwortet.
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.
Weiter in der Dokumentation
Implementierungstipps →
Wartungsmodus, Mähsaison und Darstellung des MFI
Authentifizierung →
API-Key Nutzung und Sicherheit
Endpoint /calculate →
MFI berechnen und Ergebnisdaten abrufen
Endpoint /health →
API-Status und Verfügbarkeit prüfen
API Changelog →
Änderungen, Releases und Breaking Changes
MFI API Tester →
API direkt im Browser testen
API FAQ & Begriffe →
Erklärung von Datenfeldern, Statuswerten, Checks und Modellkennzahlen
Fragen, Probleme oder Feedback?
Bei Fragen zur API, technischen Problemen, gefundenen Fehlern oder Verbesserungsvorschlägen – einfach Kontakt aufnehmen.
Kontakt aufnehmen →