Zum Inhalt springen

Fehlerbehebung bei APIs und API Manager

Diese Anleitung behandelt häufige Fehler und Probleme, die bei der Konfiguration, Veröffentlichung und Verwendung von APIs im Jitterbit API Manager auftreten. Beginnen Sie mit den Diagnoseschritten unten, um Informationen zu sammeln, und suchen Sie dann Ihr spezifisches Problem im relevanten Bereich.

Eine einheitliche Referenz mit Integrations-, Automatisierungs-, API-Management-, EDI- und App-Entwicklungsproblemen finden Sie im Harmony-Leitfaden zur Fehlerbehebung.

Alle Einträge zur Fehlerbehebung auf dieser Seite

Diagnose-Schritte

Diese Schritte gelten für die meisten API-Manager-Probleme und sind der empfohlene Ausgangspunkt.

API-Logs überprüfen

Überprüfe die API-Logs auf Anfrage- und Antwortweit-Fehler der betroffenen API. Standardmäßig zeigen die Logs Metadaten wie Statuscodes, Fehlermeldungen und Zeitstempel an, die dabei helfen können, die Ursache einzugrenzen.

Um auch die vollständigen Anfrage- und Antwort-Payloads zu erfassen, nutze den Debug-Modus – die beste Option für aktive Fehlerbehebung: Er erfasst Anfrage- und Antwortdaten zusammen mit detailliertem Protokollieren auf Aktivitätsebene und deaktiviert sich automatisch am eingestellten Datum.

  1. Aktiviere auf der Registerkarte Einstellungen der API-Konfiguration die Option Debug-Modus aktivieren bis und stelle ein Datum ein, um ihn aktiv zu halten. Siehe die Konfigurationsreferenz für benutzerdefinierte APIs, OData-Services oder Proxy-APIs.
  2. Stelle die Anfrage erneut und überprüfe die Payloads in den API-Logs.

Hinweis

Um Payloads auf Dauerbasis statt für ein festes Fehlerbehebungs-Zeitfenster zu protokollieren, nutze Ausführliches Protokollieren oder Anfrage- und Antwortweit-Payloads in Logs anzeigen für benutzerdefinierte Services und OData-Services.

Jitterbit-Systemstatus überprüfen

Wenn ein Problem alle APIs oder die API-Manager-Benutzeroberfläche selbst statt einer einzelnen API zu beeinträchtigen scheint, überprüfe die Jitterbit-Systemstatus-Seite und die bekannte Probleme-Seite, bevor du weitere Untersuchungen durchführst.

Authentifizierungs- und Sicherheitsfehler

Microsoft Entra ID OAuth: Der Name des Sicherheitsprofils darf keine Leerzeichen enthalten

  • Symptom: API-Aufrufe, die ein Microsoft Entra ID (Azure AD) dreistufiges OAuth 2.0-Sicherheitsprofil verwenden, schlagen mit einem Fehler von Microsoft fehl, das auf einen Antwort-URL-Konflikt hinweist:

    The reply URL specified in the request does not match the reply URLs configured for the application.

  • Mögliche Ursache: Der Name des Sicherheitsprofils enthält Leerzeichen. Leerzeichen im Profilnamen führen dazu, dass der OAuth-Redirect-URI falsch konstruiert wird, was keiner der in der Azure-App-Registrierung registrierten Antwort-URLs entspricht.

  • Lösung:
    1. Öffne das Sicherheitsprofil im API-Manager und benenne es um, um alle Leerzeichen zu entfernen (änder z. B. My Profile in MyProfile oder my-profile).
    2. Überprüfe in der Azure-App-Registrierung, dass die dort registrierten Antwort-URLs dem Redirect-URI entsprechen, den API-Manager für das umbenannte Profil generiert.

Microsoft Entra ID zweistufiges OAuth: OAUTH_INVALID_TOKEN_CODE-Fehler

  • Symptom: API-Aufrufe, die durch ein Microsoft Entra ID zweistufiges OAuth 2.0-Sicherheitsprofil geschützt werden, schlagen fehl mit:

    Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE

  • Mögliche Ursache: Der aud-Anspruch im JWT, das von Entra ID ausgestellt wird, stimmt nicht mit der Zielgruppe überein, die im Sicherheitsprofil des API Manager konfiguriert ist. Dies deutet normalerweise darauf hin, dass der Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder dass der OAuth-Umfang, den der Client anfordert, nicht mit dem registrierten URI übereinstimmt.

  • Lösung:
    1. Öffnen Sie im Azure-Portal die App-Registrierung, die diesem Sicherheitsprofil zugewiesen ist, und navigieren Sie zu Eine API verfügbar machen.
    2. Bestätigen Sie, dass der Application ID URI auf einen gültigen URI im Format api://<Application (client) ID> eingestellt ist.
    3. Bestätigen Sie im Sicherheitsprofil, dass der OAuth-Umfang auf api://<Application (client) ID>/.default eingestellt ist.
    4. Aktualisieren Sie die Clientanwendung, um ein Token mit genau diesem Umfang anzufordern.
    5. Wenn die Validierung auch nach Korrektur von Zielgruppe und Umfang fehlschlägt, öffnen Sie das Manifest der App-Registrierung und bestätigen Sie, dass requestedAccessTokenVersion auf 2 eingestellt ist. Ein fehlender oder anderer Wert kann auch dazu führen, dass die Token-Validierung fehlschlägt.

Azure AD Graph API ist veraltet

  • Symptom: API-Aufrufe, die zuvor mit einem Microsoft Entra ID (Azure AD)-Sicherheitsprofil funktioniert haben, schlagen mit Authentifizierungsfehlern fehl.
  • Mögliche Ursache: Die App-Registrierung des Sicherheitsprofils ist weiterhin so konfiguriert, dass die Azure AD Graph API verwendet wird, die Microsoft am 30. Juni 2025 eingestellt hat. App-Registrierungen, die nicht zu Microsoft Graph migriert wurden, schlagen fehl, wenn Anfragen gestellt werden.
  • Lösung:
    1. Migrieren Sie im Azure-Portal die App-Registrierung zu Microsoft Graph.
    2. Aktualisieren Sie nach der Migration das App-Manifest, indem Sie die Schritte für API-Berechtigungen in der Microsoft Entra ID 2-legged OAuth-Sicherheitsprofilkonfiguration ausführen.

Google oder Salesforce-Identitätsanbieter: 2-legged OAuth wird nicht unterstützt

  • Symptom: Ein API-Sicherheitsprofil, das mit Google oder Salesforce als OAuth 2.0-Identitätsanbieter konfiguriert ist, schlägt fehl, wenn es für 2-legged OAuth konfiguriert wird.
  • Mögliche Ursache: Google- und Salesforce-OAuth 2.0-API-Sicherheitsprofile unterstützen 2-legged OAuth nicht.
  • Lösung: Verwenden Sie ein 3-legged OAuth 2.0-Sicherheitsprofil für APIs, die sich mit Google oder Salesforce als Identitätsanbieter authentifizieren.

Microsoft Copilot Studio: Standardauthentifizierung wird nicht unterstützt

  • Symptom: Das Verbinden einer benutzerdefinierten Jitterbit-API mit Microsoft Copilot Studio (als REST API-Tool) schlägt fehl, wenn das Sicherheitsprofil der API Standardauthentifizierung verwendet.
  • Mögliche Ursache: Microsoft Copilot Studio unterstützt keine Standardauthentifizierung. Eine benutzerdefinierte Jitterbit-API, deren Sicherheitsprofil Standardauthentifizierung verwendet, kann nicht von Copilot Studio aufgerufen werden.
  • Lösung:
    1. Öffnen Sie im API Manager das Sicherheitsprofil, das der API zugewiesen ist.
    2. Ändern Sie den Authentifizierungstyp zu API-Schlüssel oder OAuth 2.0, oder entfernen Sie das Sicherheitsprofil aus der API, wenn der Endpunkt keine Authentifizierung erfordert.
    3. Veröffentlichen Sie die API erneut und verbinden Sie sie dann erneut in Microsoft Copilot Studio. Siehe Verbinden eines Jitterbit-KI-Agenten mit Microsoft Copilot Studio.

Schaltfläche „Neue API" ist trotz korrekter Organisationsrolle nicht sichtbar

  • Symptom: Die Schaltfläche Neue API wird im API Manager nicht angezeigt, wenn ein Benutzer eine Rolle auf Organisationsebene hat, aber kein Organisationsadministrator ist. Wenn dem Benutzer die Berechtigung Admin auf Organisationsebene gewährt wird, wird die Schaltfläche angezeigt, aber der Benutzer erhält auch Zugriff auf alle Umgebungen.
  • Mögliche Ursache: Eine Rolle auf Organisationsebene allein reicht nicht aus, um APIs zu erstellen. Die Rolle muss auch Schreibzugriff auf der Umgebungsebene für die spezifische Umgebung haben, in der der Benutzer APIs erstellen muss.
  • Lösung:
    1. Gehe in der Management Console zu Umgebungen und öffne die Umgebung, in der der Benutzer APIs erstellen muss.
    2. Bestätige, dass für die Rolle des Benutzers in dieser Umgebung der Schreibzugriff aktiviert ist. Wenn nicht, aktiviere ihn und speichere die Änderungen.
    3. Die Schaltfläche Neue API sollte jetzt für diese Umgebung sichtbar sein.

  • Symptom: Ein zwischengespeicherter Basic-Authentifizierungsberechtigungsnachweis aus einer früheren Anfrage kann einen späteren API-Aufruf auf eine dieser Weisen beeinflussen:

    • Eine API mit zwei oder mehr zugewiesenen Basic-Auth-Sicherheitsprofilen zeigt unerwartete Benutzernamen in den API-Protokollen, einschließlich Benutzernamen, die zu keinem der Profile gehören. Einige Anfragen schlagen mit dem Fehler „401 Unauthorized" fehl.
    • Eine Proxy-API oder ein OData-Dienst, dem ein Basic-Auth-Sicherheitsprofil zugewiesen ist, gibt eine erfolgreiche Antwort zurück, ohne zur Eingabe von Anmeldedaten aufzufordern.

  • Mögliche Ursache: Der Browser oder der API-Client (z. B. Postman) hat Basic-Auth-Berechtigungsnachweise aus einer früheren Sitzung als Cookie zwischengespeichert. Wenn die API erneut aufgerufen wird, sendet der Client zunächst den zwischengespeicherten Cookie. Wenn die zwischengespeicherten Berechtigungsnachweise keinem zugewiesenen Sicherheitsprofil entsprechen, wird die Anfrage abgelehnt und der unerwartete Benutzername wird in den Protokollen angezeigt, bevor die Authentifizierung mit den richtigen Anmeldedaten erfolgreich ist. Wenn sie übereinstimmen, ist die Anfrage erfolgreich, ohne dass eine neue Eingabeaufforderung erfolgt.

  • Lösung:

    1. Lösche die Cookies und den Cache des Browsers oder wechsle zu einem Inkognito- oder privaten Browserfenster, bevor du die API erneut testest.
    2. Bestätige, dass das Verhalten bei einer neuen Anfrage ohne vorherige Sitzungs-Cookies nicht auftritt. Wenn das Verhalten verschwindet, ist es eine clientseitige Zwischenspeicherung von Berechtigungsnachweisen und kein Konfigurationsproblem.

    Beachte, dass jeder HTTP-Client, der Cookies speichert (einschließlich browserbasierten Tools und API-Test-Utilities), das gleiche Verhalten aufweisen kann.

Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG

  • Symptom: Ein API-Aufruf mit einem Sicherheitsprofil, das Basic Authentication oder eine Benutzerdefinierte-Protokollierung verwendet, schlägt mit dem Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG fehl, obwohl die gleichen Anmeldedaten oder der Header-Wert zuvor funktioniert haben.

  • Mögliche Ursache: Der Wert zur Identifizierung des Aufrufers der Anfrage verstößt gegen eine Validierungsregel: Er enthält ein nicht zulässiges Zeichen (INVALID_TRIGGER_USER) oder überschreitet 256 Zeichen (TRIGGER_USER_TOO_LONG).

Zeichenvalidierung wurde in der 12.10 Harmony-Version hinzugefügt, und die Längenbegrenzung wurde in der 12.11 Harmony-Version hinzugefügt. Ein privates API-Gateway mit einer früheren Version erzwingt die entsprechende Validierung nicht, daher können beide Fehler erstmals nach dem Upgrade des Gateways auftreten, obwohl sich die Konfiguration des Sicherheitsprofils nicht geändert hat.

Ab der 12.12 Harmony-Version lehnt das Feld Benutzername des Sicherheitsprofils nicht zulässige Zeichen ab, daher lässt sich ein Sicherheitsprofil, das diese enthält, nicht mehr speichern. Für die Basic-Authentifizierung mit der Standardeinstellung Protokollierung gilt INVALID_TRIGGER_USER daher nur für Sicherheitsprofile, die vor dieser Version gespeichert wurden.

  • Lösung:
    • Für die Basic-Authentifizierung mit der Standardeinstellung Protokollierung bearbeite das Feld Benutzername des Sicherheitsprofils, um nicht zulässige Zeichen zu entfernen oder es auf 256 Zeichen oder weniger zu verkürzen, und aktualisiere anschließend die Anmeldedaten in jeder aufrufenden Anwendung, die den vorherigen Benutzernamen referenziert.
    • Für eine benutzerdefinierte Protokollierung aktualisiere die aufrufende Anwendung so, dass sie einen Headerwert sendet, der keine nicht zulässigen Zeichen enthält und 256 Zeichen oder weniger umfasst.

401 Unauthorized bei einer gültigen IP-Zulassungsliste (veralteter Cache)

  • Symptom: API-Aufrufe geben 401 Unauthorized zurück, obwohl die Client-IP korrekt in den vertrauenswürdigen IP-Gruppen des Sicherheitsprofils aufgeführt ist.
  • Mögliche Ursache: Ein veralteter Cache von älteren IP-Bereichseinträgen im Sicherheitsprofil setzt die aktiven vertrauenswürdigen IP-Gruppen außer Kraft.
  • Lösung: Migriere das Sicherheitsprofil von älteren IP-Bereichen zum Modell Vertrauenswürdige IP-Gruppen, dem aktuellen Mechanismus für die Zulassungsliste: Definiere die IPs als vertrauenswürdige IP-Gruppe und weise sie dem Profil zu. Das Deaktivieren der Einstellung Anfragen nur von den folgenden IP-Bereichen vertrauen für ein Profil, das noch ältere IP-Bereiche nutzt, entfernt diese Bereiche dauerhaft (eine Bestätigungsaufforderung warnt davor), daher migriere die IPs zu einer vertrauenswürdigen IP-Gruppe, anstatt die Einstellung auszuschalten, um den Cache zu leeren.

Salesforce on Hyperforce: Aufrufe an eine API werden nach der Änderung der Salesforce-IP-Adressen abgelehnt

  • Symptom: Aufrufe von Salesforce an eine API (ausgehende Nachrichten, Apex-Aufrufe, Salesforce Connect oder aufrufbare Aktionen) werden abgelehnt, nachdem die Salesforce-Organisation zu Hyperforce, Salesforces öffentliche Cloud-Infrastruktur, migriert wird. Das Sicherheitsprofil der API hat Anfragen nur von den folgenden IP-Bereichen vertrauen aktiviert mit einer vertrauenswürdigen IP-Gruppe, die Salesforce-IP-Adressen auflistet.

  • Mögliche Ursache: Vertrauenswürdige IP-Gruppen gleichen die Quell-IP-Adresse einer Anfrage ab, und die Adressen, die eine Salesforce-Organisation auf Hyperforce für ausgehende Aufrufe nutzt, ändern sich im Laufe der Zeit. Eine Gruppe, die einen festen Satz von Salesforce-Adressen auflistet, entspricht nicht mehr.

  • Lösung: Salesforce empfiehlt, ausgehende Aufrufe in dein Netzwerk durch Authentifizierung zu sichern, anstatt ihre Quell-IP-Adressen in eine Zulassungsliste aufzunehmen:

    1. Öffne das Sicherheitsprofil der API und setze seinen Authentifizierungstyp auf API-Schlüssel. Konfiguriere den Salesforce-Aufruf so, dass der Schlüssel in einem Request-Header gesendet wird, nicht in einem Query-Parameter, damit dieser nicht in Request-URLs aufgezeichnet wird. OAuth 2.0 ist ebenfalls verfügbar, wobei mit Salesforce als Identitätsanbieter der einzige Flow 3-legged ist, der manuelle Interaktion erfordert.

  • Nach erfolgreicher Authentifizierung des Callouts die vertrauenswürdige IP-Gruppe, die die Salesforce-Adressen auflistet, entziehen, damit spätere Adressänderungen die API nicht mehr beeinflussen. Entziehen Sie die Gruppe, anstatt Anfragen nur von den folgenden IP-Bereichen vertrauen auszuschalten, was alle noch auf dem Profil vorhandenen Legacy-IP-Bereiche dauerhaft entfernt.

Falls Ihre Organisation IP-Allowlisting benötigt, veröffentlicht Salesforce seine Hyperforce-Bereiche als dynamische Liste unter ip-ranges.salesforce.com/ip-ranges.json und kündigt Ergänzungen im Voraus an. Diese Liste ändert sich jedes Mal, wenn Salesforce seine Adressen ändert. Eine aktuelle Allowlist erfordert daher das Nachverfolgen der Datei und das Aktualisieren der vertrauenswürdigen IP-Gruppe, um sie anzupassen. Callouts von einer Adresse, die seit der letzten Aktualisierung der Gruppe hinzugefügt wurde, werden abgelehnt. Diese Adressen werden auch organisationsübergreifend in Salesforce freigegeben, sodass das Allowlisting bestätigt, woher eine Anfrage kam, nicht dass sie aus Ihrer Organisation stammte. Eine vollständige Anleitung von Salesforce, einschließlich bidirektionales SSL (mTLS), Auth Provider und verbundene Anwendungen, finden Sie unter Unterbrechungsfreien Zugriff auf Salesforce-Dienste auf Hyperforce beibehalten.

API-Veröffentlichung und Bereitstellung

API kann nicht veröffentlicht werden: API-Abonnementlimit erreicht

  • Symptom: Das Erstellen oder Veröffentlichen einer API schlägt mit einer Fehlermeldung wie dieser fehl:

    You have reached Maximum no of API Service configured for your Jitterbit organization

  • Ursache: Die Organisation hat die maximale Anzahl von veröffentlichten API-URLs erreicht, die das Abonnement zulässt. Jede veröffentlichte benutzerdefinierte API, jeder OData-Dienst oder jede Proxy-API (und alle ihre veröffentlichten Klone) verwendet eine API-URL; Entwurf-APIs werden nicht gezählt.

  • Lösung: Überprüfen Sie auf der Seite APIs des API Manager die Werte Verwendete benutzerdefinierte API-URLs und Verwendete Proxy-API-URLs (oben auf der Seite angezeigt) gegen die von Ihrem Abonnement zulässigen Gesamtzahlen. Heben Sie die Veröffentlichung von APIs auf oder löschen Sie APIs, die nicht mehr benötigt werden, um API-URLs freizugeben (Entwurf-APIs werden nicht auf das Limit angerechnet). Um das Limit zu erhöhen, wenden Sie sich an Ihren Customer Success Manager.

Veröffentlichte API gibt 404 Not Found zurück

  • Symptom: Das Aufrufen einer veröffentlichten API gibt einen 404-Fehler zurück.
  • Mögliche Ursachen:
    • Das Limit Hits pro Minute im zugewiesenen Sicherheitsprofil ist auf Null gesetzt und blockiert alle Anfragen. Eine Änderung des Abonnement-Levels Ihrer Organisation kann dieses Limit zurücksetzen, sodass eine API, die zuvor funktioniert hat, 404s zurückgeben kann.
    • Die Konfiguration, die Basis-URL oder die Sichtbarkeitseinstellungen der API sind falsch.
    • Ein privates API-Gateway erkennt die API nach der Bereitstellung nicht.
    • Die API wurde nicht vollständig veröffentlicht oder ihre Metadaten sind unvollständig.
  • Lösung:
    • Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und bestätigen Sie, dass der Wert Hits pro Minute auf eine Zahl ungleich Null gesetzt ist. Falls das Limit kürzlich zurückgesetzt wurde (z. B. nach einer Abonnementänderung), stellen Sie es auf den gewünschten Wert zurück.
    • Überprüfen Sie auf der Seite „APIs", ob die API erfolgreich veröffentlicht wurde und ob ihre URL- und Sichtbarkeitseinstellungen korrekt sind.
    • Falls die API über ein privates API-Gateway bereitgestellt wird, überprüfen Sie die Gateway-Installation und Konnektivität auf Fehler oder Fehlkonfigurationen.

Service-URL überschreitet maximale Länge (HTTP 414)

  • Symptom: Das API-Gateway gibt zurück:

    414 URI Too Large

  • Mögliche Ursache: Die erstellte Service-URL (einschließlich Basis-URL, Service-Pfad und aller Pfad- oder Query-Parameter) überschreitet 8.000 Zeichen.

  • Lösung:
    • Reduzieren Sie die Länge der Service-URL, indem Sie den Service-Pfad verkürzen oder die API in mehrere Endpoints aufteilen.
    • Bei Proxy-APIs überprüfen Sie, dass die Kombination aus Basis-URL und allen definierten Service-Pfaden das 8.000-Zeichen-Limit einhält.

API in API Manager kann nicht gelöscht werden

  • Symptom: Das Löschen einer API in API Manager schlägt fehl: Die Benutzeroberfläche zeigt einen generischen Fehler und die API wird nicht entfernt. Der Fehler tritt im Browser auf, bevor eine Löschanfrage den Server erreicht, und erscheint als JavaScript TypeError in der Browser-Entwicklerkonsole.
  • Mögliche Ursache: Die Rolle des Benutzers hat nicht die Admin-Berechtigung. Das Löschen einer API prüft zunächst, mit welchen API-Gruppen die API verknüpft ist. Das Anzeigen der Seite API-Gruppen erfordert die Admin-Berechtigung: Eine Rolle mit nur Schreib-Umgebungszugriff kann die Seite öffnen, kann aber deren Inhalte nicht lesen. Wenn die Rolle die API-Gruppen nicht lesen kann, erhält diese Prüfung einen Wert, den die Benutzeroberfläche nicht verarbeiten kann, und das Löschen wird nicht abgeschlossen.
  • Lösung: Lassen Sie einen Benutzer, dessen Rolle die Admin-Rollenberechtigung hat, das Löschen durchführen. Das Gewähren der Admin-Berechtigung für die betroffene Rolle funktioniert ebenfalls, ist aber eine breite organisationsweite Erhöhung der Berechtigungen. Daher bevorzugen Sie, dass ein vorhandener Administrator die API löscht.

API-Umgebung kann nach der Erstellung nicht geändert werden

  • Symptom: Eine API wurde in der falschen Umgebung erstellt und muss verschoben werden, aber das Umgebungsfeld ist nicht bearbeitbar.
  • Mögliche Ursache: Die Umgebung wird zum Zeitpunkt der API-Erstellung festgelegt und kann später nicht mehr geändert werden.
  • Lösung:
    • Um eine benutzerdefinierte oder Proxy-API in eine andere Umgebung zu verschieben, klonen Sie die API von der Seite „APIs" und wählen Sie die richtige Umgebung während des Klonens aus.
    • Alternativ können Sie die API aus ihrer aktuellen Umgebung exportieren und in die Zielumgebung importieren.

CORS aktiviert: OPTIONS-Anfragen werden ohne Authentifizierung ausgeführt

  • Symptom: Nach dem Aktivieren von CORS auf einer benutzerdefinierten oder Proxy-API werden Anfragen mit der HTTP-Methode OPTIONS ohne Authentifizierung verarbeitet.
  • Mögliche Ursache: Das Aktivieren von CORS führt dazu, dass Operationen mit der Methode OPTIONS ohne Authentifizierung ausgeführt werden. Dies ist erforderlich, um Browser-Preflight-Anfragen zu unterstützen, bedeutet aber, dass jede OPTIONS-Anfrage die Operation erreicht, ohne das Sicherheitsprofil zu durchlaufen.
  • Lösung:
    • Wenn die API OPTIONS nicht für sensible Operationen verwendet, ist keine Aktion erforderlich. Dies ist das erwartete Verhalten, wenn CORS aktiviert ist.
    • Falls eine authentifizierte Verarbeitung von OPTIONS erforderlich ist, deaktivieren Sie CORS auf der API oder strukturieren Sie die Operation so um, dass nicht authentifizierte Preflight-Anfragen explizit erkannt und verarbeitet werden.

Cloud-Proxy-API: Ziel-API muss öffentlich erreichbar sein

  • Symptom: Eine Proxy-API mit dem von Jitterbit gehosteten Cloud-API-Gateway gibt Fehler zurück oder kann die Ziel-API nicht erreichen.
  • Mögliche Ursache: Bei Verwendung des Cloud-API-Gateways muss die zu proxiende API aus dem öffentlichen Internet erreichbar sein. APIs hinter einer Firewall oder in einem privaten Netzwerk können vom Cloud-Gateway nicht erreicht werden.
  • Lösung:
    • Bestätigen Sie, dass die Ziel-API aus dem öffentlichen Internet erreichbar ist, auch wenn sie gesichert ist.
    • Falls die Ziel-API hinter einer Firewall bleiben muss, stellen Sie stattdessen ein privates API-Gateway im gleichen privaten Netzwerk bereit, anstatt das Cloud-API-Gateway zu verwenden.
    • Um die IP-Adressen des Cloud-Gateways auf eine Zulassungsliste zu setzen, damit das Gateway auf die zu proxiende API zugreifen kann, siehe Informationen zur Zulassungsliste.

Die Einstellung „Request & Response Payloads anzeigen" hat keine Auswirkung auf Proxy-APIs

  • Symptom: Die Umschaltfläche Request & Response Payloads in Logs anzeigen wird in den Einstellungen einer Proxy-API angezeigt, aber das Aktivieren hat keine Auswirkung auf die Protokollausgabe.
  • Mögliche Ursache: Das Logging von Request- und Response-Payloads wird für Proxy-APIs nicht unterstützt. Die Umschaltfläche ist in der Konfigurationsoberfläche sichtbar, funktioniert aber nicht für diesen API-Typ.
  • Lösung: Um Request- und Response-Payloads zu erfassen, verwenden Sie eine benutzerdefinierte API, die denselben Endpunkt aufruft, wobei die Einstellung Request & Response Payloads in Logs anzeigen unterstützt wird.

Leistung und Timeouts

HTTP 504 Gateway Timeout

  • Symptom: API-Aufrufe geben Folgendes zurück:

    504 Gateway Timeout

    Dies tritt normalerweise auf, nachdem das Timeout-Fenster des Gateways abgelaufen ist (30 bis 180 Sekunden, abhängig von der Timeout-Einstellung der API).

  • Mögliche Ursachen:

    • Die API-URL ist falsch formatiert, oder Pfadparameter werden nicht korrekt verarbeitet, was dazu führt, dass das Gateway beim Weiterleiten der Anfrage fehlschlägt.
    • Die Backend-Operation oder der externe Service reagiert zu langsam, um innerhalb des Timeout-Fensters des Gateways zu antworten. Dies kann z. B. an großen Payloads oder komplexer Transformationslogik liegen.
    • Die Anfrage kann keinem verfügbaren Agent zugewiesen werden, z. B. weil die Agent-Gruppe mit voller Parallelität ausgelastet ist oder unter hoher Last steht. Sie läuft daher beim Gateway in einen Timeout, bevor die Operation ausgeführt wird. Ein Zeichen für diesen Fall ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Operationsprotokollen hat.

  • Lösung:

    • Überprüfen Sie, dass die API-URL korrekt formatiert ist. Falls die API Pfadparameter verwendet, erwägen Sie, der Operation ein Skript hinzuzufügen, das die URL explizit analysiert und die Parameterwerte erfasst.
    • Falls das Timeout durch ein langsames Backend verursacht wird, überprüfen Sie die Operation und die zugehörige Transformationslogik auf Performance-Engpässe, insbesondere große Datenmengen oder langsame externe Aufrufe, und reduzieren Sie den langsamen Schritt.
    • Falls die Operation genuinely mehr Zeit benötigt, als die aktuelle Einstellung erlaubt, erhöhen Sie das Timeout auf der Registerkarte „API-Einstellungen". Das API-Timeout (Standard 30 Sekunden, Maximum 180 Sekunden) ist unabhängig vom Studio-Operationstimeout. Das Operationstimeout wird nur auf privaten Agents verwendet, wenn die EnableAPITimeout-Einstellung in der Agent-Konfiguration aktiviert ist.
    • Falls die Operation nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeit-Antwort nicht erforderlich ist, gestalten Sie die Operation der API so um, dass die lang laufende Arbeit asynchron gestartet wird (z. B. durch Aufrufen mit RunOperation im asynchronen Modus), damit die API eine Antwort zurückgeben kann, ohne auf den Abschluss zu warten. Siehe Asynchrone Operationen verwalten.
    • Bei zeitweiligen Timeouts fügen Sie Wiederholungen hinzu, damit ein vorübergehender Fehler erneut versucht wird: Verwenden Sie die integrierten Wiederholungseinstellungen der HTTP v2-Verbindung für ausgehende Aufrufe oder eine skriptgesteuerte RunOperation-Wiederholungsschleife mit einer Verzögerung zwischen den Versuchen.
    • Falls Timeouts mit der Agent-Last korrelieren, überprüfen Sie die Agent-Kapazität: Führen Sie API-bedienende Operationen auf Agents aus, die von schweren ETL-Workloads getrennt sind, und fügen Sie der Gruppe Agents hinzu, falls sie überlastet ist. Siehe Optimieren und verbessern Sie die Leistung von Jitterbit-Private-Agents.

Private Gateway gibt eine Seite „verify Jitterbit Services" mit HTTP 400 zurück, ohne API-Logeintrag

  • Symptom: Anfragen über ein privates API-Gateway schlagen zeitweise mit einer HTTP-400-Antwort fehl. Anstelle einer normalen API-Antwort erhält der Aufrufer eine HTML-Fehlerseite ähnlich wie:

    Error connecting to Jitterbit Services. Please verify that all Jitterbit Services are running on your Jitterbit Agent machine - including the Apache server and Process Engine.

    Es wird kein Eintrag in den API-Logs für die fehlgeschlagene Anfrage angezeigt, da die Anfrage keine Operation erreicht hat.

  • Mögliche Ursache: Die private Agent-Gruppe ist überlastet und hat keine verfügbaren Apache-Worker-Threads, um Jobs vom privaten API-Gateway zu akzeptieren. Wenn kein Worker-Thread frei ist, schlägt die Übergabe vom Gateway zum Agent mit einem Verbindungsabbruch fehl, bevor die Anfrage protokolliert oder ausgeführt werden kann.

  • Lösung:
    1. Fügen Sie der Agent-Gruppe weitere Agents hinzu, um die Last zu verteilen, und bestätigen Sie, dass die Agent-Hosts ausreichend CPU und Arbeitsspeicher haben.
    2. Überwachen Sie die Apache-Worker-Thread-Nutzung der Agents. Wenn native Observability aktiviert ist, überprüfen Sie die Diagramme Apache Thread Capability, Apache idle workers und Apache busy workers (siehe Dashboards), um zu bestätigen, ob Threads während der Ausfälle erschöpft sind.
    3. Wenn die Agents auch nach der Skalierung konsistent die Apache-Worker-Threads erschöpfen, wenden Sie sich an den Jitterbit Support, um die Apache-Worker-Thread-Kapazität der Agents zu überprüfen (die Einstellung MaxRequestWorkers). Ändern Sie die Jitterbit-Apache-Konfigurationsdateien nur auf Anweisung des Jitterbit-Supports. Siehe Apache-Konfigurationsdateien.

Anzeige und Synchronisierung

API-Portal spiegelt Projektänderungen nicht wider

  • Symptom: Das API-Portal zeigt veraltete Projektnamen oder Attribute an, nachdem ein Projekt umbenannt oder aktualisiert wurde.
  • Mögliche Ursache: Das API-Portal wurde nach der Projektänderung nicht automatisch synchronisiert.
  • Lösung:
    1. Um alle benutzerdefinierten und Proxy-APIs in der Umgebung zu aktualisieren, öffnen Sie den Portal Manager und klicken Sie auf Regenerate Docs. Um eine einzelne API zu aktualisieren, öffnen Sie deren Registerkarte Documentation auf der Seite APIs und klicken Sie auf Save & Publish.
    2. Vergewissern Sie sich, dass die aktualisierten Informationen korrekt im API-Portal angezeigt werden.

Sicherheitsprofiländerungen dauern mehrere Minuten, bis sie wirksam werden

  • Symptom: Eine API verhält sich weiterhin so, als würde eine alte Sicherheitsprofilkonfiguration aktiv sein, auch nachdem das Profil aktualisiert und gespeichert wurde.
  • Mögliche Ursache: Sicherheitsprofile werden auf dem API-Gateway zwischengespeichert. Änderungen an einem aktiven Sicherheitsprofil werden nicht sofort wirksam.
  • Lösung:
    1. Warten Sie mehrere Minuten nach dem Speichern einer Sicherheitsprofiländerung, bevor Sie die betroffene API testen.
    2. Wenn das Problem nach 10 Minuten weiterhin besteht, bestätigen Sie, dass die Änderung korrekt gespeichert wurde, indem Sie das Sicherheitsprofil erneut öffnen.

Das Löschen einer API aktualisiert die API-Portal-Dokumentation nicht

  • Symptom: Nach dem Löschen einer API bleibt ihre OpenAPI-Dokumentation im API-Portal sichtbar.
  • Mögliche Ursache: Die API-Portal-Dokumentation wird nicht automatisch aktualisiert, wenn eine API aus API Manager gelöscht wird.
  • Lösung:
    • Nach dem Löschen einer API öffnen Sie den Portal Manager und entfernen oder aktualisieren Sie dort manuell den Dokumentationseintrag der API.
    • Alternativ können Sie die Registerkarte Documentation für die API verwenden, bevor Sie sie löschen, um den Portal-Eintrag zuerst zu entfernen.

Sicherheitsprofil kann nicht gelöscht werden, solange es einer veröffentlichten API zugewiesen ist

  • Symptom: Der Versuch, ein Sicherheitsprofil zu löschen, schlägt fehl oder die Löschoption ist nicht verfügbar, auch nachdem das Profil von einer API entfernt wurde.
  • Mögliche Ursache: Nach dem Entfernen eines Sicherheitsprofils aus der API-Konfiguration muss die API gespeichert und erneut veröffentlicht werden, damit das Profil als vollständig nicht zugewiesen gilt. Bis die API erneut veröffentlicht wird, behandelt API Manager das Profil weiterhin als in Verwendung.
  • Lösung:
    1. Nach dem Entfernen des Sicherheitsprofils von der API auf Speichern und dann auf Veröffentlichen klicken.
    2. Nachdem die API mit der aktualisierten Konfiguration erneut veröffentlicht wurde, wird das Sicherheitsprofil nicht mehr als in Verwendung angezeigt und kann gelöscht werden.

Probleme mit dem privaten Gateway

2-legged OAuth fällt auf 3-legged OAuth bei privaten Gateway-Versionen vor 10.48 zurück

  • Symptom: Ein für 2-legged OAuth konfiguriertes Sicherheitsprofil verwendet stattdessen 3-legged OAuth, wenn es über ein privates API-Gateway bereitgestellt wird.
  • Mögliche Ursache: Private API-Gateways mit einer Version älter als 10.48 unterstützen 2-legged OAuth nicht. Wenn die Gateway-Version unter 10.48 liegt, fällt das Sicherheitsprofil auf 3-legged OAuth zurück, auch wenn 2-legged OAuth konfiguriert ist.
  • Lösung:
    1. Die Version des privaten API-Gateways überprüfen, das die API bereitstellt.
    2. Das Gateway auf Version 10.48 oder später aktualisieren, um die Unterstützung für 2-legged OAuth zu aktivieren.

Multi-Gateway ALB: Alle Container müssen sich auf demselben Host befinden

  • Symptom: In einer containerisierten Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) schlagen API-Aufrufe intermittierend fehl oder Payloads können nicht abgerufen werden, obwohl einzelne Gateways fehlerfrei erscheinen.
  • Mögliche Ursache: Bei Verwendung eines containerisierten privaten API-Gateways mit einem ALB müssen alle Gateway-Container auf demselben Host-Computer ausgeführt werden. Container, die auf verschiedenen Hosts bereitgestellt werden, können die Payload-Abrufung nicht koordinieren, was zu intermittierenden Ausfällen führt.
  • Lösung:
    1. Bestätigen, dass alle privaten API-Gateway-Container in der Gruppe auf demselben physischen oder virtuellen Host ausgeführt werden.
    2. Wenn Container auf mehrere Hosts verteilt sind, diese auf einem einzelnen Host zusammenfassen.
    3. Für Multi-Host-Bereitstellungen die ALB-Konfiguration im Gateway-Installationsleitfaden überprüfen, um weitere Konfigurationsanforderungen zu sehen.

Privates Gateway: Benutzerdefinierte SSL-Konfiguration wird durch Upgrades überschrieben

  • Symptom: Nach dem Upgrade eines privaten API-Gateways werden benutzerdefinierte SSL-Protokoll- oder Cipher-Einstellungen nicht mehr angewendet und das Gateway kehrt zum standardmäßigen TLS-Verhalten zurück.
  • Mögliche Ursache: Der Upgrade-Prozess des privaten API-Gateways überschreibt die On-Premise-Konfigurationsdatei (/usr/local/openresty/nginx/conf/onpremise.conf). Alle manuellen Änderungen an dieser Datei, einschließlich benutzerdefinierter SSL-Protokoll-Einschränkungen oder Cipher-Listen, gehen während des Upgrades verloren.
  • Lösung:
    1. Vor dem Upgrade des privaten API-Gateways die On-Premise-Konfigurationsdatei sichern.
    2. Nach Abschluss des Upgrades die benutzerdefinierten SSL-Einstellungen auf die neue Konfigurationsdatei anwenden.

Private Gateway gibt HTTP 507 oder "No such file or directory" zurück

  • Symptom: Private-API-Gateway-Endpoints geben 507 Insufficient Storage zurück. Gateway-Logs zeigen:

    could not open payload file: No such file or directory

    obwohl auf den Gateway-Hosts ausreichend Speicherplatz vorhanden ist.

  • Mögliche Ursache: Hier bedeutet 507, dass das Gateway die gehostete Payload- oder Antwortdatei für die Anfrage nicht öffnen konnte; dies bedeutet nicht unbedingt, dass der Host keinen Speicher hat. Bei einem Multi-Node-Private-API-Gateway hinter einem Load Balancer kann dies passieren, wenn der Node, der eine Anfrage verarbeitet, nicht auf eine gehostete Datei zugreifen kann, die ein anderer Node erstellt hat, da diese Dateien lokal auf jedem Node gespeichert sind.

  • Lösung:

    1. Bestätigen Sie, dass die Gateway-Hosts nicht wirklich voll sind, indem Sie die Festplatte und Inode-Auslastung prüfen (df -h und df -i). Geben Sie Speicherplatz frei und führen Sie den Test erneut durch, nur wenn diese wirklich voll sind.
    2. Wenn das Gateway als mehrere Nodes hinter einem Load Balancer läuft, stellen Sie sicher, dass der Load Balancer jede Anfrage und deren Antwort konsistent zum selben Node leitet, da gehostete Payload- und Antwortdateien lokal auf dem Node gespeichert sind, der sie erstellt hat. Für containerisierte Gateways siehe Multi-Gateway ALB: Alle Container müssen auf demselben Host sein.
    3. Wenn der Fehler weiterhin auftritt, aktivieren Sie Trace-Logging auf dem Gateway (setzen Sie traceLogsEnabled auf true in der Gateway-Konfiguration) und kontaktieren Sie den Jitterbit-Support mit den resultierenden Trace-Logs, den Gateway-Logs (/opt/jitterbit/var/log/api-gateway), den NGINX- oder OpenResty-Logs und der ls -lR-Ausgabe für die hosted-files-Verzeichnisse auf jedem Node. Support kann serverseitige Bedingungen prüfen, die nicht vom Kunden konfigurierbar sind, wie die Host-zu-Umgebungs-Zuordnung, veraltete Private-Domain-Einträge und Dateiberechtigungen.

Private-Gateway-Installation oder -Upgrade schlägt mit fehlenden Abhängigkeiten fehl

  • Symptom: Die Ausführung von yum install zur Installation oder zum Upgrade eines Linux- (RPM-) Private-API-Gateway auf Version 10.62 oder später schlägt mit Fehlern zu fehlenden Abhängigkeiten fehl:

    Nothing provides geoip-devel needed by jitterbit-api-gateway-11.x.x-x.x86_64
Nothing provides libGeoIP.so.1()(64bit) needed by jitterbit-api-gateway-11.x.x-x.x86_64

  • Mögliche Ursache: Private-API-Gateway-Version 10.62 und später benötigen die Pakete geoip-devel und libGeoIP, die vom EPEL-Repository bereitgestellt werden. Die dokumentierte Installation aktiviert EPEL vor der Installation des Gateways. Der Fehler tritt auf, wenn dieser Schritt übersprungen wird oder wenn der Gateway-Host keinen Internetzugang hat und EPEL nicht erreichen kann, um die Pakete herunterzuladen.

  • Lösung:

    • Auf einem Gateway-Host mit Internetzugang aktivieren Sie das EPEL-Repository vor der Installation des Gateways, wie unter Private-API-Gateway installieren beschrieben: Führen Sie yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm aus, und führen Sie dann die Gateway-Installation erneut aus.
    • Auf einem abgetrennten Host ohne Internetzugang führt die Installation des Pakets epel-release allein nur die Repository-Definition hinzu; die Pakete geoip-devel und libGeoIP werden nicht heruntergeladen. Laden Sie auf einer Maschine mit Internetzugang diese Pakete und ihre transitiven Abhängigkeiten herunter, übertragen Sie sie auf den Gateway-Host, und installieren Sie sie in Abhängigkeitsreihenfolge mit yum install <package.rpm>, bevor Sie die Gateway-Installation erneut ausführen.

Private-Gateway-Selbsttest gibt "Failure, test call to API failed" zurück

  • Symptom: Das Befehlszeilen-Selbsttestprogramm des Private-API-Gateway gibt zurück:

    Failure, test call to API failed

  • Mögliche Ursache: Bei Private-API-Gateway-Versionen 11.30 und früher erstellt das Selbsttestprogramm eine Test-API, bei der erforderliche Felder (Service Name und Path) fehlen, was zum Fehlschlag des Testaufrufs führt.

  • Lösung:
    • Upgraden Sie das Private-API-Gateway auf Version 11.31 oder später, was dies automatisch behebt.
    • Wenn ein sofortiges Upgrade nicht möglich ist: Öffnen Sie die API-Konfiguration für die API namens ApiGatewayTest, füllen Sie das Feld Service Name mit einem beliebigen Wert (z. B. service), setzen Sie Path auf /, speichern und veröffentlichen Sie, führen Sie dann das Selbsttestprogramm erneut aus.

Analytik und API-Verhalten

OData $count oder $inlinecount gibt einen Fehler zurück, wenn keine Datensätze übereinstimmen

  • Symptom: Eine OData-Serviceabfrage mit den Systemabfrageoptionen $count oder $inlinecount gibt einen Fehler statt 0 zurück, wenn keine Datensätze dem Filter entsprechen.
  • Mögliche Ursache: Ein OData-Service gibt standardmäßig einen Fehler statt 0 zurück, wenn eine $count- oder $inlinecount-Abfrage keine Datensätze findet.
  • Lösung: Setzen Sie auf privaten Agenten mit Version 11.32 oder später den OData-Parameter $noErrorOnZeroCount in der OData-Service-Konfiguration auf true. Dies führt dazu, dass $count-Abfragen 0 statt eines Fehlers zurückgeben, wenn keine Datensätze übereinstimmen.

Proxy-API: Bindestriche in Request-Headern durch Unterstriche ersetzt

  • Symptom: Eine Proxy-API-Operation erhält Request-Header, bei denen Bindestriche durch Unterstriche ersetzt wurden (beispielsweise kommt X-Custom-Header als X_Custom_Header an), was dazu führt, dass Header-Abfragen fehlschlagen.
  • Mögliche Ursache: Proxy-APIs verfügen über eine disable-hyphen-replacement-Einstellung, die steuert, ob Bindestriche in Request-Header-Namen durch Unterstriche ersetzt werden. Bei neuen Proxy-APIs ist diese Einstellung standardmäßig auf true gesetzt (Ersetzung deaktiviert). Ältere Proxy-APIs können die Einstellung auf false gesetzt haben, was zur Ersetzung führt.
  • Lösung:
    • Überprüfen Sie in der Proxy-API-Konfiguration die Header-Einstellung disable-hyphen-replacement. Um Bindestriche in Header-Namen beizubehalten, stellen Sie sicher, dass die Einstellung auf true gesetzt ist.
    • Falls die Proxy-API vor Einführung dieses Standards erstellt wurde und die Ersetzung unerwartet auftritt, aktualisieren Sie die Einstellung auf true und veröffentlichen Sie die API erneut.

Operationsprotokolle sind nicht sichtbar für API-ausgelöste Operationen, wenn der Debug-Modus deaktiviert ist

  • Symptom: Nach dem Aufrufen einer API zeigt das API-Protokoll an, dass der Aufruf erfolgreich ausgeführt wurde, aber auf der Seite Runtime erscheint kein Operationsprotokoll für die Operation, die die API ausgelöst hat. Aufrufe von WriteToOperationLog aus der Operation erzeugen ebenfalls keine sichtbaren Protokolleinträge.
  • Mögliche Ursache: Wenn eine Operation über eine veröffentlichte API ausgelöst wird, werden erfolgreiche Ausführungen standardmäßig nicht in den Operationsprotokollen angezeigt. Fehlgeschlagene Operationen werden immer protokolliert; nur erfolgreiche Operationsprotokolle und alle WriteToOperationLog-Ausgaben aus erfolgreichen Ausführungen sind verborgen. Erfolgreiche Ausführungen werden nur angezeigt, wenn Enable debug mode until (eine API Manager-Einstellung) oder Operation debug logging (eine Agent-Einstellung) aktiviert ist.
  • Lösung:
    1. Um erfolgreiche Operationsprotokolle und WriteToOperationLog-Ausgaben zu sehen, aktivieren Sie Enable debug mode until für die API auf der Registerkarte „API-Einstellungen", oder aktivieren Sie Operation debug logging auf dem Agent.
    2. Um auch die Rohdaten von Anfrage und Antwort sowie die Nutzlasten zu erfassen, aktivieren Sie entweder Enable debug mode until (wie in Schritt 1), oder kombinieren Sie Operation debug logging mit Show Request & Response Payloads in Logs und Verbose logging. Welche Daten jede Einstellung erfasst, hängt von der aktivierten Kombination ab; für eine vollständige Aufschlüsselung siehe API-Anfrage- und Antwortdaten.
    3. Deaktivieren Sie den Debug-Modus, nachdem Sie die benötigten Protokolle erfasst haben, da das Belassen aktiv das Protokollvolumen erhöht.

API-Payload ist 2 Tage lang auf dem Agent verfügbar

  • Symptom: Ein Workflow, der eine API-Anfragepayload mehr als 2 Tage nach dem API-Aufruf vom Agent abruft, kann die Payload nicht finden.
  • Mögliche Ursache: API-Anfragepayloads für benutzerdefinierte APIs und OData-Services werden maximal 2 Tage lang auf dem Agent gespeichert. Danach ist die Payload nur noch verfügbar, wenn der Vorgang sie bereits in einen persistenten Speicher-Connector geschrieben hat (z. B. Temporary Storage, File Share oder eine Datenbank).
  • Lösung:
    • Gestalten Sie Vorgänge, die API-Anfragepayloads verarbeiten, so, dass sie die Daten sofort bei dem API-Aufruf verarbeiten, anstatt den Payload-Abruf zu verschieben.
    • Falls die Payload für längere Verarbeitung beibehalten werden muss, schreiben Sie sie im ursprünglichen API-ausgelösten Vorgang an einen persistenten Speicherort.

API Logs-Seite behält vorherige Filterauswahl bei

  • Symptom: Die Seite API Logs zeigt nicht die erwarteten Protokolleinträge an, obwohl die API erfolgreich ausgeführt wird.
  • Mögliche Ursache: Die Seite API Logs merkt sich Filterauswahl aus der vorherigen Sitzung. Ein zuvor angewendeter Filter verbirgt möglicherweise die erwarteten Ergebnisse.
  • Lösung: Überprüfen Sie auf der Seite API Logs alle aktiven Filter und löschen Sie alle Filter, die die erwarteten Einträge ausschließen könnten.

Unveröffentlichte APIs erscheinen nicht in der Analytics-Dropdown für APIs

  • Symptom: Eine API wird nicht in der Dropdown APIs auf der Seite Analytics angezeigt, daher können Analysedaten für diese API nicht gefiltert werden.
  • Mögliche Ursache: Nur aktuell veröffentlichte APIs erscheinen in der Dropdown APIs. APIs, die unveröffentlicht wurden, werden aus der Dropdown ausgeschlossen, auch wenn API-Protokolle für diese APIs vorhanden sind.
  • Lösung:
    • Bestätigen Sie, dass die API veröffentlicht wurde. Um Analysedaten anzuzeigen, muss die API veröffentlicht sein.
    • Um Protokolleinträge für eine unveröffentlichte API anzuzeigen, verwenden Sie stattdessen die Seite API Logs. Protokolldaten bleiben dort verfügbar, können aber nicht nach API-Name gefiltert werden.

Ratenlimitierung

Fehler 429: Monatliche API-Zugriffsvergütung überschritten

  • Symptom: Alle APIs in der Organisation geben plötzlich HTTP 429-Fehler zurück.
  • Mögliche Ursache: Die Organisation hat ihre monatliche API-Zugriffsvergütung gemäß ihrer Lizenz aufgebraucht. Wenn die Vergütung überschritten wird, werden alle API-Aufrufe für den Rest des Monats mit einer 429-Antwort abgelehnt.
  • Lösung:
    • Überprüfen Sie die aktuelle Zugriffszahl gegen Ihre monatliche Vergütung auf der APIs-Seite. Die Vergütung wird am ersten Tag des folgenden Monats zurückgesetzt.
    • Um ein Erreichen des Limits zu vermeiden, konfigurieren Sie Ratenlimits auf Umgebungs- oder Security-Profile-Ebene mit der Einstellung Zugriffe pro Minute, um Last zu verteilen und Verbrauchslimits pro Consumer zu erzwingen.
    • Um die monatliche Vergütung Ihrer Organisation zu erhöhen, kontaktieren Sie Ihren Customer Success Manager.

Fehler 429: Consumer-IP nicht im vertrauenswürdigen IP-Bereich

  • Symptom: Ein bestimmter Consumer oder eine Anwendung erhält HTTP 429-Fehler beim Aufrufen einer API, während andere Consumer die gleiche API erfolgreich aufrufen können.
  • Mögliche Ursache: Das Sicherheitsprofil, das der API zugeordnet ist, hat vertrauenswürdige IP-Gruppen konfiguriert. Anfragen von IP-Adressen außerhalb der zulässigen Bereiche werden mit einer 429-Antwort abgelehnt.
  • Lösung:
    1. Öffnen Sie das Sicherheitsprofil, das der API zugeordnet ist, und überprüfen Sie die Konfiguration der vertrauenswürdigen IP-Gruppe.
    2. Fügen Sie die IP-Adresse oder den Adressbereich des Consumers zu einer vorhandenen vertrauenswürdigen IP-Gruppe hinzu, oder erstellen Sie eine neue vertrauenswürdige IP-Gruppe mit den erforderlichen Adressen.

Plattformweite Ratenbegrenzung: 200 Anfragen pro Minute

  • Symptom: APIs, die auf dem von Jitterbit verwalteten Cloud-API-Gateway gehostet werden, werden bei hohem Datenverkehr gedrosselt oder mit einer 429 Too Many Requests-Antwort abgelehnt, auch wenn die Ratenlimits des Sicherheitsprofils nicht erreicht wurden.
  • Mögliche Ursache: Das von Jitterbit verwaltete Cloud-API-Gateway erzwingt ein plattformweites Limit von 200 API-Anfragen pro Minute pro Organisation, das über alle API-Typen (Custom, Proxy und OData) hinweg geteilt wird. Dieses Limit gilt nicht für private API-Gateways.
  • Lösung:
    • Überprüfen Sie Ihre API-Verkehrsmuster und verteilen Sie Aufrufe über die Zeit, wenn möglich, um innerhalb des Limits von 200 Anfragen pro Minute zu bleiben.
    • Wenn Ihr Anwendungsfall einen über dieses Limit hinaus gehenden Durchsatz erfordert, stellen Sie ein privates API-Gateway bereit, bei dem der Durchsatz durch die Kapazität des Host-Servers und nicht durch eine plattformweite Obergrenze bestimmt wird.

Netzwerk und Konnektivität

Zscaler oder SSL-abfangende Firewall blockiert API-Zugriff

  • Symptom: API-Aufrufe schlagen mit Zertifikatfehlern fehl, oder Backend-Endpunkte können nicht auf APIs zugreifen, die mit TLS gesichert sind, wenn diese über ein von Zscaler verwaltetes oder ähnliches SSL-inspizierendes Netzwerk weitergeleitet werden.
  • Mögliche Ursachen:
    • Zscaler und ähnliche Security-Proxys führen SSL/TLS-Inspektion durch, indem sie HTTPS-Datenverkehr abfangen und ihn mit ihrem eigenen CA-Zertifikat erneut signieren. Client-Systeme, die der Zscaler-Root-CA nicht vertrauen, lehnen die Verbindung ab.
    • Das manuelle Importieren des Jitterbit-Zertifikats in den Vertrauensspeicher ist keine zuverlässige Umgehungslösung: Wenn Jitterbit sein Zertifikat erneuert, wird die manuell importierte Kopie veraltet und bricht die Verbindung erneut.
  • Lösung:
    • Installieren Sie das Zscaler-Root-CA-Zertifikat im Vertrauensspeicher des Betriebssystems oder Browsers auf den Systemen, die die API-Aufrufe tätigen, damit von Zscaler erneut signierte Zertifikate vertraut werden.
    • Für Tools wie curl, wget oder openssl konfigurieren Sie diese so, dass sie den im Zscaler-Umfeld definierten HTTP-Proxy verwenden.
    • Fordern Sie eine Zscaler-Richtlinienausnahme für die Jitterbit-API-Gateway-Hostnamen an, um SSL-Inspektion für diese spezifischen Ziele zu umgehen.
    • Überprüfen Sie die Regeln der PAC-Datei (Proxy-Auto-Konfiguration) Ihrer Organisation, um zu bestätigen, dass Jitterbit-Endpunkte korrekt verarbeitet werden.
    • Importieren Sie das Jitterbit-Leaf-Zertifikat nicht manuell in einen Vertrauensspeicher als Umgehungslösung: Verwenden Sie stattdessen die Zscaler-Root-CA, um Unterbrechungen bei Zertifikaternuerungen durch Jitterbit zu vermeiden.