Jede Ablehnung der Management-REST-API ist ein JSON-Body mit einem HTTP-Status. Diese Seite erklärt, wie man ihn liest, welche Limits es gibt und wie Ihre Integration darauf reagieren sollte.
Der Fehler-Body
Die meisten Fehler sehen so aus:
{
"message": "The device limit of this account is reached.",
"code": "FORBIDDEN",
"details": { "key": "max_devices", "limit": 43, "current": 43, "adding": 1 }
}| Feld | Bedeutung |
|---|---|
message | Ein englischer Satz für Menschen. Nicht parsen: Er kann sich ändern. |
code | Ein stabiler Code für die Art des Fehlers (Tabelle unten) |
details | Vorhanden, wenn der Client mehr tun kann: reason (ein stabiler maschineller Code), key (ein Tarif-Limit), keys, issues |
Varianten:
| Fall | Body |
|---|---|
| Ein Body oder eine Abfrage, die eine Feldregel verletzt | 400 { "message": "Validation error", "issues": [{ "path": ["name"], "message": "…" }] } |
| Einige Routen prüfen den Body selbst | 400 { "message": "<the problems, joined with commas>" } |
| Ungültiges JSON | 400 { "message": "Malformed request body" } |
| Ein unerwarteter Serverfehler | 500 { "message": "Internal server error" } (die Ursache wird bei uns protokolliert, nicht angezeigt) |
Verzweigen Sie zuerst nach dem Status, dann nach code und details.reason. Jede Routenreferenz listet ihre Gründe auf.
Statuscodes
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
| 200, 201 | Erledigt (201: erstellt) | |
| 202 | Angenommen, läuft noch (ein Befehl) | Ergebnis später abrufen |
| 400 | Die Anfrage ist nicht gültig | Anfrage korrigieren; nicht unverändert wiederholen |
| 401 | Keine gültige Anmeldung: „Ungültiger oder abgelaufener API-Schlüssel.“ | Schlüssel prüfen; nicht wiederholen |
| 403 | Der Schlüssel oder sein Inhaber darf dies nicht, der Schlüssel ist von dieser Adresse nicht erlaubt oder ein Tarif-Limit ist erreicht | Berechtigungen des Schlüssels und Rolle des Inhabers prüfen; bei details.key den Tarif |
| 404 | Nicht gefunden oder für Sie nicht sichtbar | ID und Berechtigungen des Schlüssels prüfen |
| 405 | Die Methode ist hier nicht erlaubt (zum Beispiel das Schreiben von Client-Attributen) | |
| 409 | Ein Konflikt: ein Duplikat, ein Datensatz, der noch verwendet wird, ein Zustand, der die Aktion nicht zulässt, oder eine Änderung durch jemand anderen | Erneut lesen, dann entscheiden |
| 412 | Der Datensatz wurde seit dem Lesen geändert (If-Match) | Erneut lesen und Ihre Änderung neu anwenden |
| 413 | Der Body oder die Datei ist zu groß | Weniger senden |
| 415 | Falscher Content-Type (MCP-Server) | application/json senden |
| 422 | Der Inhalt verletzt eine Geschäftsregel | Inhalt korrigieren |
| 428 | Ein erforderlicher Vorbedingungs-Header fehlt (If-Match) | Ihn senden |
| 429 | Ein Ratenlimit | Retry-After Sekunden warten, dann erneut versuchen |
| 500 | Ein Fehler auf unserer Seite | Später mit Backoff erneut versuchen |
| 503 | Vorübergehend nicht verfügbar, zum Beispiel wenn Ihre Organisation umzieht: „Dieser Workspace ist schreibgeschützt, während er umgezogen wird. Bitte versuchen Sie es später erneut.“ (code TENANT_READ_ONLY, Retry-After: 300) | Nach Retry-After erneut versuchen; Lesezugriffe funktionieren weiter |
Codes
code | Typischer Status |
|---|---|
VALIDATION_ERROR | 400, 413, 422, 428 |
UNAUTHORIZED | 401 |
FORBIDDEN | 403 |
FEATURE_NOT_AVAILABLE | 403: Ihr Tarif enthält die Funktion nicht |
TENANT_SUSPENDED, TENANT_INACTIVE | 403: Ihre Organisation ist nicht aktiv |
TENANT_IP_NOT_ALLOWED | 403: Die IP-Regeln Ihrer Organisation lehnen diese Adresse ab |
NOT_FOUND | 404 |
CONFLICT | 409, 412 |
RATE_LIMIT_EXCEEDED | 429 |
INTERNAL_ERROR | 500, 503 |
Tarif-Limits
Ein Tarif-Limit ist ein 403 mit details.key, das das Limit benennt, details.limit mit seinem Wert und details.current mit Ihrem aktuellen Zählerstand, zum Beispiel max_devices beim Anlegen eines Geräts. Siehe Nutzung und Kontingente und Tarife und das IoT-Add-on.
Ratenlimits
Mehrere Limits gelten für jeden Aufruf mit API-Schlüssel. Jedes antwortet mit 429, wenn es aufgebraucht ist.
| Limit | Standard | Geltungsbereich | Meldung |
|---|---|---|---|
| Adress-Limit | 120 Anfragen pro Minute, bis zu 120 gleichzeitig | Pro aufrufender IP-Adresse | „Zu viele Anfragen. Bitte versuchen Sie es später erneut.“ |
| Tarif-Limit | Durch Ihren Tarif festgelegt (keines, wenn der Tarif keines festlegt) | Pro Organisation, alle Schlüssel und angemeldeten Mitglieder zusammen | „Das API-Ratenlimit Ihres Tarifs wurde erreicht. Bitte versuchen Sie es gleich noch einmal oder upgraden Sie Ihren Tarif.“ |
| Schlüssel-Limit | 1.000 Aufrufe pro Uhrminute (Per-Key Rate Limit in den Einstellungen des API-Schlüssels) | Pro Schlüssel | „API-Schlüssel-Ratenlimit überschritten. Bitte verlangsamen Sie.“ |
Einige Routen fügen eigene hinzu:
| Route | Limit |
|---|---|
| Befehle | 10 pro Gerät und Minute („Zu viele Befehle an dieses Gerät; versuchen Sie es in einer Minute erneut.“, Retry-After: 60); 600 pro Organisation und Minute („Zu viele Anfragen für Ihren Tarif. Bitte upgraden Sie oder versuchen Sie es später erneut.“, X-RateLimit-Scope: tenant-plan) |
| Schreibvorgänge für Geräteeinstellungen | 600 pro Organisation und Minute |
| MCP-Server | 120 Lese- und 20 Schreib-Tool-Aufrufe pro Anmeldedaten und Minute |
Header bei einem 429
| Header | Bedeutung |
|---|---|
Retry-After | Sekunden, bis ein Aufruf wieder angenommen wird |
RateLimit-Limit, X-RateLimit-Limit | Das Limit pro Minute |
RateLimit-Remaining, X-RateLimit-Remaining | Verbleibende Aufrufe (0) |
RateLimit-Reset | Sekunden, bis das Kontingent wieder voll ist |
Nicht jede 429 trägt jeden Header. Fehlt Retry-After, warten Sie 60 Sekunden.
Das Adress-Limit füllt sich kontinuierlich: Alle eine halbe Sekunde kommt ein Aufruf zurück, daher löst ein gleichmäßiger Takt von 2 Aufrufen pro Sekunde es nie aus. Verteilen Sie Lastspitzen, statt sie auf einmal zu senden.
Sicher erneut versuchen
- Nur
429,500,502,503und504sowie Netzwerkfehler erneut versuchen. Retry-Afterwarten, falls vorhanden; sonst exponentiell zurückgehen (1, 2, 4, 8 … Sekunden, bis zu einer Minute) mit etwas zufälligem Jitter.- Nach einigen Versuchen aufgeben und den letzten Body protokollieren.
- Bevor Sie ein
POSTwiederholen, das etwas anlegt (ein Gerät, einen Befehl), prüfen Sie, ob der erste Aufruf gewirkt hat: zuerst auflisten oder lesen. Ein Befehls-POSThat keinen Idempotency-Key. - Nie
400,401,403,404oder422unverändert wiederholen.
async function call(url, init, tries = 5) {
for (let i = 0; ; i++) {
const res = await fetch(url, init);
if (res.ok || i === tries - 1 || ![429, 500, 502, 503, 504].includes(res.status)) return res;
const wait = Number(res.headers.get('Retry-After')) || Math.min(60, 2 ** i) + Math.random();
await new Promise((r) => setTimeout(r, wait * 1000));
}
}Fehler, die Ihnen zuerst begegnen können
| Sie sehen | Wahrscheinliche Ursache |
|---|---|
401 bei jedem Aufruf | Ein Tippfehler im Schlüssel, ein abgelaufener oder widerrufener Schlüssel oder ein Schlüssel einer anderen Organisation (die tenantId im Pfad muss die des Schlüssels sein) |
403 „API key does not have the required permission.“ | Dem Schlüssel fehlt die Berechtigung der Route. Bearbeiten Sie die Modulberechtigungen des Schlüssels. |
403 „You are not permitted to perform this action“ | Der Schlüssel hat die Berechtigung, sein Inhaber aber nicht mehr (Rolle geändert, Gruppe entfernt, Zugriffsrichtlinie) |
403 „This API key may not be used from the current IP address.“ | Die IP-Allowlist des Schlüssels oder die Standardliste der Organisation |
404 für einen Datensatz, den Sie in der App sehen | Der Inhaber sieht ihn über eine Berechtigung, die der Schlüssel nicht hat, oder die ID gehört zu einer anderen Organisation |
429 nur von einem Server | Das Adress-Limit: Aufrufe verteilen oder weniger, dafür größere Seiten verwenden |