Fehler, Limits und Wiederholungsversuche

API Clients sollten ihre Entscheidungen anhand von HTTP-Statuscodes, stabilen Fehlercodes und Antwort-Headern treffen. Quotenwerte dürfen nicht anhand des Plannamens fest codiert werden: Gateway- und Dienstbeschränkungen richten sich nach dem aktiven Plan, der Konfiguration durch den Administrator, dem Profil und der aktuellen Produktrichtlinie.

Fehlerumschlag

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

Einige über einen Proxy bereitgestellte Dienste können einen dienstspezifischen Envelope zurückgeben. Behalten Sie stets den HTTP-Status und den Antworttext in strukturierten Diagnoseprotokollen bei, schwärzen Sie jedoch Anmeldedaten und sensible Benutzerdaten.

Häufige Statusmeldungen

Status	Bedeutung	Kundenmaßnahme
400	Ungültiges Anfrageformat oder ungültiger Parameter	Korrigieren Sie die Anfrage; wiederholen Sie sie nicht unverändert.
401	Fehlende, ungültige, abgelaufene oder widerrufene Anmeldeinformationen	Ersetzen oder erneuern Sie die Anmeldeinformationen.
403	Der Vorgang wurde aufgrund von Richtlinien für Geltungsbereich, Dienst, Rolle, Tarif, Kontingent, IP-Adresse oder Ressource abgelehnt	Überprüfen Sie den Fehlercode und die aktuelle Konfiguration des Kontos.
404	Die Route oder die angeforderte Ressource wurde nicht gefunden	Überprüfen Sie die VersionAPI, den Pfad, die Kennung und die Sichtbarkeit der Ressource.
409	Der Vorgang steht im Konflikt mit dem aktuellen Ressourcenstatus	Aktualisieren Sie den Status, bevor Sie entscheiden, ob ein erneuter Versuch unternommen werden soll.
429	Ein aktuelles Minuten- oder Tageslimit für Anfragen wurde erreicht	Warten Sie auf Retry-After; reduzieren Sie die Parallelität oder die Abfragehäufigkeit.
500	Die Anfrage erreichte einen Dienst, der unerwartet ausgefallen ist	Wiederholen Sie den Versuch nur, wenn die Operation sicher wiederholt werden kann.
502, 503, 504	Eine Abhängigkeit, eine Steuerung oder ein Dienst war vorübergehend nicht verfügbar	Wenden Sie ein begrenztes exponentielles Backoff mit Jitter an.

Gateway-Fehlercodes können Folgendes umfassen: MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE, und INTERNAL_ERROR. Ziel-Dienste können zusätzliche Codes für ihre eigenen Ressourcen und Kontingente zurückgeben.

Live-Limit-Header

Zu den erfolgreichen und abgelehnten authentifizierten Anfragen können gehören:

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

Lesen Sie diese Werte zur Laufzeit aus. Die Limits können je nach Tarif, Konto, Profil, Administratorrichtlinie und Release-Stufe variieren und können sich ohne eine Client- Version ändern.

Wiederholungsstrategie

Verwenden Sie bei vorübergehenden Status ein begrenztes exponentielles Backoff mit Jitter. Eine sinnvolle Abfolge beginnt bei etwa einer Sekunde und steigt bis zu einer moderaten maximalen Verzögerung an. Berücksichtigen Sie einen größeren Retry-After Wert, sofern vorhanden.

Führen Sie eine Wiederholung nur durch, wenn der Vorgang sicher ist:

• GET Anfragen können in der Regel sicher wiederholt werden.
• Ein fehlgeschlagener Erstellungs-, Sende- oder Aktualisierungsvorgang kann bereits abgeschlossen sein, bevor die Verbindung abgebrochen ist. Überprüfen Sie den Status der Ressource, bevor Sie den Vorgang wiederholen.
• Nicht wiederholen 400, 401, oder die meisten 403 Antworten, ohne die Anfrage oder die Anmeldeinformationen zu ändern.
• Legen Sie eine maximale Anzahl von Versuchen fest und geben Sie eine aussagekräftige Fehlermeldung aus, sobald diese erreicht ist.

Reduzieren Sie unnötigen Datenverkehr

• Speichern Sie schreibgeschützte Berechtigungs- oder Metadaten-Antworten für einen angemessenen kurzen Zeitraum im Cache, anstatt sie bei jeder UI-Interaktion erneut zu überprüfen.
• Bevorzugen Sie Webhooks für unterstützte Ereignisse.
• Fassen Sie identische Anfragen aus derselben Workload zusammen.
• Paginieren Sie große Sammlungen und vermeiden Sie unbegrenzte Parallelität.
• Verwenden Sie die CLI’s --json Geben Sie die Ausgabe in Skripten aus, anstatt doppelteAPI Anfragen zur Formatierung zu stellen.

Diagnose einer unerwarteten Zugriffsverweigerung

1. Aufruf GET /v1/auth/whoami um die aktive Identität und den Schlüssel zu bestätigen.
2. Aufruf GET /v1/auth/quota für den aktuellen Snapshot der Gateway-Kontingente.
3. Stellen Sie sicher, dass der Schlüssel über den für die Route erforderlichen Geltungsbereich verfügt.
4. Vergewissern Sie sich, dass der Zielservice für das aktive Profil aktiviert ist.
5. Überprüfen Sie die Rollen- und Organisationsberechtigungen im Ziel-Service.
6. Notieren Sie den Status, den Fehlercode, die Antwort-Header und den Zeitpunkt der Anfrage, bevor Sie sich an CHAMPREP Support.