Zum Inhalt springen

Fehlerbehebung für APIs und API Manager

Diese Anleitung behandelt häufige Fehler und Probleme, die beim Konfigurieren, Veröffentlichen und Verwenden 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 Abschnitt.

Eine einheitliche Referenz, die Integrations-, Automatisierungs-, API-Management-, EDI- und App-Entwicklungsprobleme an einem Ort abdeckt, finden Sie im Harmony-Fehlerbehebungsleitfaden.

Alle Fehlerbehebungseinträge auf dieser Seite

Diagnoseschritte

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

API-Protokolle prüfen

Überprüfen Sie die API-Protokolle auf Anfrage- und Antwortfehler der betroffenen API. Standardmäßig zeigen die Protokolle 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, verwenden Sie den Debug-Modus, die beste Option für aktive Fehlerbehebung: Er erfasst Anfrage- und Antwortdaten zusammen mit detailliertem Aktivitäts-Logging und wird automatisch am festgelegten Datum deaktiviert.

  1. Aktivieren Sie auf der Registerkarte Einstellungen der API-Konfiguration Debug-Modus aktivieren bis und legen Sie ein Datum fest, um ihn aktiv zu halten. Siehe die Konfigurationsreferenz für benutzerdefinierte APIs, OData-Services oder Proxy-APIs.
  2. Wiederholen Sie die Anfrage und überprüfen Sie dann die Payloads in den API-Protokollen.

Hinweis

Um Payloads fortlaufend statt für ein festes Fehlerbehebungsfenster zu protokollieren, verwenden Sie Ausführliches Logging oder Anfrage- und Antwort-Payloads in Protokollen anzeigen für benutzerdefinierte und OData-Services.

Jitterbit-Systemstatus prüfen

Wenn ein Problem alle APIs oder die API Manager-Benutzeroberfläche selbst statt einer einzelnen API zu beeinflussen scheint, überprüfen Sie die Jitterbit-Systemstatusseite und die Seite Bekannte Probleme, bevor Sie weitere Untersuchungen durchführen.

Authentifizierungs- und Sicherheitsfehler

Microsoft Entra ID OAuth: Sicherheitsprofilname darf keine Leerzeichen enthalten

  • Symptom: API-Aufrufe mit einem Microsoft Entra ID (Azure AD) OAuth 2.0-Sicherheitsprofil mit drei Beinen schlagen mit einem Fehler von Microsoft fehl, der 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 Sicherheitsprofilname 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. Öffnen Sie das Sicherheitsprofil im API Manager und benennen Sie es um, um Leerzeichen zu entfernen (ändern Sie beispielsweise My Profile in MyProfile oder my-profile).
    2. Überprüfen Sie 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 2-legged OAuth: OAUTH_INVALID_TOKEN_CODE-Fehler

  • Symptom: API-Aufrufe, die durch ein Microsoft Entra ID OAuth 2.0-Sicherheitsprofil mit zwei Beinen geschützt sind, 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 im API Manager-Sicherheitsprofil konfigurierten Zielgruppe überein. Dies deutet normalerweise darauf hin, dass der Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder der OAuth-Bereich, 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 API verfügbar machen.
    2. Bestätigen Sie, dass der Application ID URI auf einen gültigen URI im Format api://<Application (client) ID> gesetzt ist.
    3. Bestätigen Sie im Sicherheitsprofil, dass der OAuth-Bereich auf api://<Application (client) ID>/.default gesetzt ist.
    4. Aktualisieren Sie die Clientanwendung, um ein Token mit diesem genauen Bereich anzufordern.
    5. Wenn die Validierung nach Korrektur der Zielgruppe und des Bereichs weiterhin fehlschlägt, öffnen Sie das Manifest der App-Registrierung und bestätigen Sie, dass requestedAccessTokenVersion auf 2 gesetzt ist. Ein fehlender oder anderer Wert kann ebenfalls zu Fehlern bei der Token-Validierung führen.

Azure AD Graph API wurde eingestellt

  • Symptom: API-Aufrufe, die zuvor mit einem Microsoft Entra ID (Azure AD)-Sicherheitsprofil funktionierten, schlagen mit Authentifizierungsfehlern fehl.
  • Mögliche Ursache: Die App-Registrierung des Sicherheitsprofils ist weiterhin für die Verwendung der Azure AD Graph API konfiguriert, die Microsoft am 30. Juni 2025 eingestellt hat. App-Registrierungen, die nicht zu Microsoft Graph migriert wurden, schlagen bei Anfragen fehl.
  • 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 befolgen.

Google oder Salesforce Identity Provider: 2-legged OAuth wird nicht unterstützt

  • Symptom: Ein API-Sicherheitsprofil, das mit Google oder Salesforce als OAuth 2.0 Identity Provider konfiguriert ist, schlägt fehl, wenn es für 2-legged OAuth konfiguriert wird.
  • Mögliche Ursache: OAuth 2.0 API-Sicherheitsprofile von Google und Salesforce 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 Identity Provider 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 von 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 Sie einen Jitterbit AI-Agent mit Microsoft Copilot Studio.

"New API"-Schaltfläche trotz korrekter Organisationsrolle nicht sichtbar

  • Symptom: Die Schaltfläche New API wird im API Manager für einen Benutzer mit einer Organisationsrolle, der aber kein Organisationsadministrator ist, nicht angezeigt. Wenn man dem Benutzer die Berechtigung Admin auf Organisationsebene erteilt, wird die Schaltfläche angezeigt, aber es werden auch alle Umgebungen für den Benutzer freigegeben.
  • Mögliche Ursache: Eine Organisationsrolle allein reicht nicht aus, um APIs zu erstellen. Die Rolle muss auch Write-Zugriff auf Umgebungsebene für die spezifische Umgebung haben, in der der Benutzer APIs erstellen muss.
  • Lösung:
    1. Gehen Sie in der Management Console zu Environments und öffnen Sie die Umgebung, in der der Benutzer APIs erstellen muss.
    2. Bestätigen Sie für die Rolle des Benutzers in dieser Umgebung, dass Write-Zugriff aktiviert ist. Falls nicht, aktivieren Sie ihn und speichern Sie.
    3. Die Schaltfläche New API sollte jetzt für diese Umgebung sichtbar sein.
  • Symptom: 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 einem 401-Fehler (Unauthorized) fehl.
  • Mögliche Ursache: Der Browser oder API-Client (z. B. Postman) hat Basic-Auth-Anmeldedaten aus einer vorherigen Sitzung als Cookie zwischengespeichert. Wenn die API erneut aufgerufen wird, sendet der Client zuerst den zwischengespeicherten Cookie. Wenn die zwischengespeicherten Anmeldedaten nicht mit einem der konfigurierten Sicherheitsprofile übereinstimmen, wird die Anfrage abgelehnt und der unerwartete Benutzername wird in den Protokollen angezeigt, bevor die Authentifizierung mit den korrekten Anmeldedaten erfolgreich ist.

  • Lösung:

    1. Löschen Sie die Cookies und den Cache des Browsers, oder wechseln Sie zu einem Inkognito- oder privaten Browserfenster, bevor Sie die API erneut testen.
    2. Bestätigen Sie, dass das Verhalten nicht vorhanden ist, wenn eine neue Anfrage ohne vorherige Sitzungs-Cookies gestellt wird. Wenn der Fehler verschwindet, ist das Problem clientseitiges Caching von Anmeldedaten und kein Konfigurationsproblem.

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

Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG

  • Symptom: Ein API-Aufruf mit einem Sicherheitsprofil mit Basic Authentication oder einer Custom-Logging-Einstellung schlägt mit einem 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, der zur Identifizierung des Aufrufers der Anfrage verwendet wird, verstößt gegen eine Validierungsregel: Er enthält ein nicht zulässiges Zeichen (INVALID_TRIGGER_USER) oder überschreitet 256 Zeichen (TRIGGER_USER_TOO_LONG).

    • Bei Basic Authentication mit der Standard-Logging-Einstellung ist dieser Wert das Feld User name des Sicherheitsprofils.
    • Bei einer Custom-Logging-Einstellung ist es der Wert, den die aufrufende Anwendung im konfigurierten Header sendet.

    Die Zeichenvalidierung wurde in der 12.10 Harmony-Version hinzugefügt, und das Längenlimit wurde in der 12.11 Harmony-Version hinzugefügt. Ein privates API Gateway, das eine frühere Version ausführt, erzwingt die entsprechende Validierung nicht, daher können beide Fehler zum ersten Mal nach dem Upgrade des Gateways angezeigt werden, obwohl sich die Konfiguration des Sicherheitsprofils nicht geändert hat.

  • Lösung:
    • Für Standardauthentifizierung mit der Standardeinstellung Protokollierung bearbeiten Sie das Feld Benutzername des Sicherheitsprofils, um die nicht zulässigen Zeichen zu entfernen oder es auf 256 Zeichen oder weniger zu kürzen, und aktualisieren Sie dann die Anmeldedaten in jeder aufrufenden Anwendung, die auf den vorherigen Benutzernamen verweist.
    • Für eine benutzerdefinierte Protokollierung aktualisieren Sie die aufrufende Anwendung so, dass sie einen Header-Wert sendet, der keine nicht zulässigen Zeichen enthält und 256 Zeichen oder weniger umfasst.

401 Unauthorized mit 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 Legacy-IP-Bereichseinträgen im Sicherheitsprofil setzt die aktiven vertrauenswürdigen IP-Gruppen außer Kraft.
  • Lösung: Migrieren Sie das Sicherheitsprofil von Legacy-IP-Bereichen zum Modell Vertrauenswürdige IP-Gruppen, dem aktuellen Zulassungsmechanismus: Definieren Sie die IPs als vertrauenswürdige IP-Gruppe und weisen Sie sie dem Profil zu. Das Deaktivieren der Einstellung Anfragen nur von den folgenden IP-Bereichen vertrauen in einem Profil, das noch Legacy-IP-Bereiche verwendet, entfernt diese Bereiche dauerhaft (eine Bestätigungsaufforderung warnt davor), daher migrieren Sie die IPs zu einer vertrauenswürdigen IP-Gruppe, anstatt die Einstellung auszuschalten, um den Cache zu löschen.

Salesforce on Hyperforce: Aufrufe an eine API werden nach Ä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 öffentlicher 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 verwendet, ändern sich im Laufe der Zeit. Eine Gruppe, die einen festen Satz von Salesforce-Adressen auflistet, stimmt nicht mehr überein.

  • Lösung: Salesforce empfiehlt, ausgehende Aufrufe in Ihr Netzwerk zu authentifizieren, anstatt ihre Quell-IP-Adressen in die Zulassungsliste aufzunehmen:

    1. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und setzen Sie seinen Authentifizierungstyp auf API-Schlüssel. Konfigurieren Sie den Salesforce-Aufruf so, dass der Schlüssel in einem Request-Header gesendet wird, nicht in einem Query-Parameter, damit er 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.

    2. Nachdem sich der Aufruf erfolgreich authentifiziert hat, heben Sie die Zuweisung der vertrauenswürdigen IP-Gruppe auf, die die Salesforce-Adressen auflistet, damit spätere Adressänderungen die API nicht mehr beeinflussen. Heben Sie die Zuweisung der Gruppe auf, anstatt Anfragen nur von den folgenden IP-Bereichen vertrauen auszuschalten, was alle noch im Profil vorhandenen Legacy-IP-Bereiche dauerhaft entfernt.

    Wenn Ihre Organisation IP-Zulassungslisten 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, daher bedeutet das Aktualisieren einer Zulassungsliste, die Datei zu verfolgen und die vertrauenswürdige IP-Gruppe entsprechend zu aktualisieren. Aufrufe von einer Adresse, die seit der letzten Aktualisierung der Gruppe hinzugefügt wurde, werden abgelehnt. Diese Adressen werden auch über Salesforce-Organisationen hinweg gemeinsam genutzt, daher bestätigt das Zulassungslisten dieser Adressen, woher eine Anfrage kam, nicht dass sie von Ihrer Organisation kam. Vollständige Anleitung von Salesforce, einschließlich bidirektionales SSL (mTLS), Auth Providers und verbundene Apps, finden Sie unter Retain uninterrupted access to Salesforce services on Hyperforce.

API-Veröffentlichung und -Bereitstellung

API kann nicht veröffentlicht werden: Limit für Abonnement-APIs 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 veröffentlichter API-URLs erreicht, die das Abonnement zulässt. Jede veröffentlichte benutzerdefinierte API, jeder OData-Service oder Proxy-API (und jeder ihrer veröffentlichten Klone) verwendet eine API-URL; Entwurf-APIs zählen nicht.

  • Lösung: Überprüfen Sie auf der Seite APIs des API-Managers die Anzahl der verwendeten Custom-API-URLs und verwendeten Proxy-API-URLs, die oben auf der Seite angezeigt werden, 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 zählen nicht gegen das Limit). Um das Limit zu erhöhen, wenden Sie sich an Ihren Customer Success Manager.

Veröffentlichte API gibt 404 Not Found zurück

  • Symptom: Der Aufruf 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 der Abonnementstufe der Organisation kann dieses Limit zurücksetzen, sodass eine API, die zuvor funktioniert hat, 404-Fehler 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. Wenn das Limit kürzlich zurückgesetzt wurde (z. B. nach einer Abonnementänderung), stellen Sie es auf den beabsichtigten Wert wieder her.
    • Überprüfen Sie auf der Seite APIs, ob die API erfolgreich veröffentlicht wurde und ob ihre URL und Sichtbarkeitseinstellungen korrekt sind.
    • Wenn 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 folgende Meldung zurück:

    414 URI Too Large

  • Mögliche Ursache: Die konstruierte Service-URL (einschließlich Basis-URL, Service-Pfad und aller Pfad- oder Abfrageparameter) ü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 Endpunkte aufteilen.
    • Bestätigen Sie bei Proxy-APIs, dass die Kombination der Basis-URL und aller definierten Service-Pfade innerhalb des 8.000-Zeichen-Limits bleibt.

Proxy-API: Service-Pfad-Parameter erfordern ein OpenAPI-Dokument

  • Symptom: Das Konfigurieren eines Proxy-API-Service-Pfads mit Pfadparametern (z. B. /resource/{id}) schlägt fehl, wenn er manuell eingegeben wird, da das Feld keine geschweiften Klammern akzeptiert.
  • Mögliche Ursache: Manuell definierte Service-Pfade in Proxy-APIs unterstützen nicht die Zeichen { und }, die zur Definition von Pfadparametern verwendet werden.
  • Lösung: Um Pfadparameter in einem Proxy-API-Service-Pfad zu verwenden, stellen Sie ein OpenAPI-Dokument bereit, das die Pfade und ihre Parameter definiert. Der API-Manager erkennt die Pfade und ihre Parameter automatisch aus der OpenAPI-Spezifikation, anstatt sie manuell eingeben zu müssen.

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 an und die API wird nicht entfernt. Der Fehler tritt im Browser auf, bevor eine Löschanfrage den Server erreicht, und wird als JavaScript TypeError in der Browser-Entwicklerkonsole angezeigt.
  • Mögliche Ursache: Die Rolle des Benutzers verfügt nicht über die Admin-Berechtigung. Beim Löschen einer API wird zunächst überprüft, welchen API-Gruppen die API zugeordnet ist. Das Anzeigen der Seite API-Gruppen erfordert die Admin-Berechtigung: Eine Rolle mit nur Write-Umgebungszugriff kann die Seite öffnen, aber nicht deren Inhalte lesen. Wenn die Rolle die API-Gruppen nicht lesen kann, erhält diese Überprü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, stellt aber eine umfassende Erhöhung auf Organisationsebene dar. Daher ist es vorzuziehen, 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 danach 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 während des Klonens die richtige Umgebung 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 verarbeitet die HTTP-Methode OPTIONS Anfragen ohne Authentifizierung.
  • 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.
    • Wenn eine authentifizierte Verarbeitung von OPTIONS erforderlich ist, deaktivieren Sie CORS auf der API oder strukturieren Sie die Operation so um, dass unauthentifizierte Preflight-Anfragen explizit erkannt und verarbeitet werden.

Cloud-Proxy-API: Ziel-API muss öffentlich zugänglich sein

  • Symptom: Eine Proxy-API, die das von Jitterbit gehostete Cloud-API-Gateway verwendet, gibt Fehler zurück oder kann die Ziel-API nicht erreichen.
  • Mögliche Ursache: Bei Verwendung des Cloud-API-Gateways muss die API, die als Proxy fungiert, über das öffentliche 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 über das öffentliche Internet erreichbar ist, auch wenn sie gesichert ist.
    • Wenn die Ziel-API hinter einer Firewall bleiben muss, stellen Sie stattdessen ein privates API-Gateway im selben privaten Netzwerk bereit, anstatt das Cloud-API-Gateway zu verwenden.
    • Um die IP-Adressen des Cloud-Gateways auf die Whitelist zu setzen, damit das Gateway auf die Proxy-API zugreifen kann, siehe Whitelist-Informationen.

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

  • Symptom: Der Umschalter 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: Die Protokollierung von Request- und Response-Payloads wird für Proxy-APIs nicht unterstützt. Der Umschalter ist in der Konfigurationsoberfläche sichtbar, funktioniert aber nicht für diesen API-Typ.
  • Lösung: Um Request- und Response-Payloads zu erfassen, verwende 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 nach dem Timeout-Fenster des Gateways auf (30 bis 180 Sekunden, abhängig von der Timeout-Einstellung der API).

  • Mögliche Ursachen:

    • Die API-URL ist fehlerhaft, oder Pfadparameter werden nicht korrekt verarbeitet, was dazu führt, dass das Gateway beim Routing der Anfrage fehlschlägt.
    • Der Backend-Betrieb oder der externe Service antwortet zu langsam innerhalb des Timeout-Fensters des Gateways, beispielsweise aufgrund großer Payloads oder komplexer Transformationslogik.
    • Die Anfrage kann keinem verfügbaren Agent zugewiesen werden, beispielsweise weil die Agent-Gruppe vollständig ausgelastet ist oder unter hoher Last steht, sodass ein Timeout am Gateway auftritt, bevor der Betrieb ausgeführt wird. Ein Zeichen für diesen Fall ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Betriebsprotokollen hat.

  • Lösung:

    • Überprüfe, dass die API-URL korrekt formatiert ist. Wenn die API Pfadparameter verwendet, erwäge das Hinzufügen eines Skripts zum Betrieb, das die URL explizit analysiert und die Parameterwerte erfasst.
    • Wenn das Timeout durch ein langsames Backend verursacht wird, überprüfe den Betrieb und seine Transformationslogik auf Leistungsengpässe, insbesondere große Datenmengen oder langsame externe Aufrufe, und reduziere den langsamen Schritt.
    • Wenn der Betrieb wirklich mehr Zeit benötigt als die aktuelle Einstellung zulässt, erhöhe das Timeout auf der Registerkarte „API-Einstellungen". Das API-Timeout (Standard 30 Sekunden, Maximum 180 Sekunden) ist unabhängig vom Studio-Betriebstimeout; das Betriebstimeout wird nur auf privaten Agents verwendet, wenn die Einstellung EnableAPITimeout in der Agent-Konfiguration aktiviert ist.
    • Wenn der Betrieb nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeitantwort nicht erforderlich ist, gestalte den Betrieb der API so um, dass die langfristige Arbeit asynchron gestartet wird (beispielsweise durch Aufrufen mit RunOperation im asynchronen Modus), damit die API eine Antwort zurückgeben kann, ohne auf den Abschluss zu warten. Siehe Asynchrone Betriebe verwalten.
    • Bei zeitweiligen Timeouts füge Wiederholungen hinzu, damit ein vorübergehender Fehler erneut versucht wird: Verwende die integrierten Wiederholungseinstellungen der HTTP v2-Verbindung für ausgehende Aufrufe oder eine skriptgesteuerte RunOperation-Wiederholungsschleife mit einer Verzögerung zwischen den Versuchen.
    • Wenn Timeouts mit der Agent-Last korrelieren, überprüfe die Agent-Kapazität: Führe API-Betriebe auf Agents aus, die von schweren ETL-Workloads getrennt sind, und füge Agents zur Gruppe hinzu, wenn diese überlastet ist. Siehe Optimiere und verbessere die Leistung von Jitterbit-Private-Agents.

Private Gateway gibt eine 400-Seite „Jitterbit Services überprüfen" ohne API-Logeintrag zurück

  • Symptom: Anfragen über ein privates API-Gateway schlagen zeitweise mit einer HTTP-400-Antwort fehl. Statt 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 erscheint kein Eintrag in den API-Logs für die fehlgeschlagene Anfrage, da die Anfrage nie einen Vorgang 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 anzunehmen. Wenn kein Worker-Thread frei ist, schlägt die Gateway-zu-Agent-Übergabe 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 über ausreichend CPU und Speicher verfügen.
    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 dem Skalieren konsistent keine Apache-Worker-Threads mehr haben, kontaktieren Sie den Jitterbit-Support, um die Apache-Worker-Thread-Kapazität der Agents zu überprüfen (die Einstellung MaxRequestWorkers). Ändern Sie die Jitterbit-Apache-Konfigurationsdateien nicht, es sei denn, der Jitterbit-Support weist Sie dazu an. 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. Überprüfen Sie, 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 ob eine alte Sicherheitsprofil-Konfiguration aktiv ist, obwohl 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 dem API Manager gelöscht wird.
  • Lösung:
    • Nach dem Löschen einer API öffnen Sie den Portal Manager und entfernen oder aktualisieren Sie den Dokumentationseintrag der API dort manuell.
    • Alternativ können Sie die Registerkarte Documentation für die API vor dem Löschen verwenden, um den Portal-Eintrag zuerst zu entfernen.

Sicherheitsprofil kann nicht gelöscht werden, während es noch 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, bevor das Profil als vollständig zugewiesen gilt. Bis die API erneut veröffentlicht wird, behandelt API Manager das Profil weiterhin als in Verwendung.
  • Lösung:
    1. Nachdem das Sicherheitsprofil von der API entfernt wurde, klicken Sie auf Speichern und dann auf Veröffentlichen der API.
    2. Sobald 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 privaten Gateways

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

  • Symptom: Ein Sicherheitsprofil, das für 2-legged OAuth konfiguriert ist, verwendet stattdessen 3-legged OAuth, wenn es über ein privates API-Gateway bereitgestellt wird.
  • Mögliche Ursache: Private API-Gateways vor Version 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. Überprüfen Sie die Version des privaten API-Gateways, das die API bereitstellt.
    2. Aktualisieren Sie das Gateway auf Version 10.48 oder später, 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 zeitweise 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 zeitweisen Ausfällen führt.
  • Lösung:
    1. Bestätigen Sie, 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, konsolidieren Sie sie auf einem einzelnen Host.
    3. Für Multi-Host-Bereitstellungen überprüfen Sie die ALB-Konfiguration im Gateway-Installationshandbuch auf zusätzliche Konfigurationsanforderungen.

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 Standard-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-Protokollbeschränkungen oder Cipher-Listen, gehen während des Upgrades verloren.
  • Lösung:
    1. Sichern Sie die On-Premise-Konfigurationsdatei, bevor Sie das private API-Gateway aktualisieren.
    2. Nachdem das Upgrade abgeschlossen ist, wenden Sie Ihre benutzerdefinierten SSL-Einstellungen auf die neue Konfigurationsdatei an.

Private Gateway gibt HTTP 507 oder „Datei oder Verzeichnis nicht vorhanden" zurück

  • Symptom: Private API-Gateway-Endpunkte geben 507 Insufficient Storage zurück. Gateway-Protokolle 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 mehr hat. In einem Multi-Node-Private-API-Gateway hinter einem Load Balancer kann dies vorkommen, 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 vorhanden sind.

  • Lösung:

    1. Bestätigen Sie, dass die Gateway-Hosts nicht wirklich keinen Speicher mehr haben, indem Sie die Festplatte und die Inode-Nutzung überprü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 ausgeführt wird, bestätigen Sie, dass der Load Balancer jede Anfrage und ihre Antwort konsistent zum selben Node leitet, da gehostete Payload- und Antwortdateien lokal auf dem Node vorhanden sind, der sie erstellt hat. Für containerisierte Gateways siehe Multi-Gateway ALB: Alle Container müssen sich auf demselben Host befinden.
    3. Wenn der Fehler weiterhin besteht, aktivieren Sie die Trace-Protokollierung auf dem Gateway (setzen Sie traceLogsEnabled auf true in der Gateway-Konfiguration) und kontaktieren Sie den Jitterbit-Support mit den resultierenden Trace-Protokollen, den Gateway-Protokollen (/opt/jitterbit/var/log/api-gateway), den NGINX- oder OpenResty-Protokollen und der ls -lR-Ausgabe für die hosted-files-Verzeichnisse auf jedem Node. Der Support kann serverseitige Bedingungen überprüfen, die nicht vom Kunden konfigurierbar sind, wie z. B. die Host-zu-Umgebungs-Zuordnung, veraltete Private-Domain-Einträge und Dateiberechtigungen.

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

  • Symptom: Das Ausführen von yum install zum Installieren oder Aktualisieren eines Linux-Private-API-Gateways (RPM) 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 erfordern 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:

    • Aktivieren Sie auf einem Gateway-Host mit Internetzugang 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 durch.
    • Auf einem isolierten Host ohne Internetzugang wird durch die Installation des Pakets epel-release allein nur die Repository-Definition hinzugefügt; die Pakete geoip-devel und libGeoIP werden nicht heruntergeladen. Laden Sie auf einem Computer 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 durchführen.

Private Gateway-Selbsttest gibt „Fehler, Testaufruf an API fehlgeschlagen" zurück

  • Symptom: Das Befehlszeilen-Selbsttest-Dienstprogramm des Private API Gateway gibt Folgendes zurück:

    Failure, test call to API failed

  • Mögliche Ursache: In Private API Gateway Version 11.30 und früher erstellt das Selbsttest-Dienstprogramm eine Test-API, der erforderliche Felder (Service Name und Path) fehlen, was dazu führt, dass der Testaufruf fehlschlägt.

  • Lösung:
    • Aktualisieren 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 mit dem Namen 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 Selbsttest-Dienstprogramm 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 Systemabfrageopionen $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: Auf privaten Agenten mit Version 11.32 oder später den OData-Parameter $noErrorOnZeroCount in der OData-Service-Konfiguration auf true setzen. 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 empfängt Request-Header, bei denen Bindestriche durch Unterstriche ersetzt wurden (z. B. kommt X-Custom-Header als X_Custom_Header an), was dazu führt, dass Header-Lookups fehlschlagen.
  • Mögliche Ursache: Proxy-APIs haben 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 auf false gesetzt sein, was die Ersetzung verursacht.
  • Lösung:
    • In der Proxy-API-Konfiguration die disable-hyphen-replacement-Header-Einstellung überprüfen. Um Bindestriche in Header-Namen beizubehalten, sicherstellen, dass die Einstellung auf true gesetzt ist.
    • Falls die Proxy-API vor Einführung dieses Standards erstellt wurde und die Ersetzung unerwartet auftritt, die Einstellung auf true aktualisieren und die API erneut veröffentlichen.

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, dass der Aufruf erfolgreich war, aber auf der Seite Runtime erscheint kein Operationsprotokoll für die Operation, die die API ausgelöst hat. Aufrufe von WriteToOperationLog innerhalb der Operation erzeugen ebenfalls keine sichtbaren Protokolleinträge.
  • Mögliche Ursache: Wenn eine Operation über eine veröffentlichte API ausgelöst wird, erscheinen erfolgreiche Ausführungen standardmäßig nicht in den Operationsprotokollen. Fehlgeschlagene Operationen werden immer protokolliert; nur erfolgreiche Operationsprotokolle und alle WriteToOperationLog-Ausgaben aus erfolgreichen Ausführungen werden ausgeblendet. Erfolgreiche Ausführungen erscheinen nur, wenn Enable debug mode until (eine API-Manager-Einstellung) oder Operation debug logging (eine Agent-Einstellung) aktiv ist.
  • Lösung:
    1. Um erfolgreiche Operationsprotokolle und WriteToOperationLog-Ausgaben anzuzeigen, Enable debug mode until für die API auf der Registerkarte API-Einstellungen aktivieren oder Operation debug logging auf dem Agent aktivieren.
    2. Um auch die Rohdaten von Request und Response sowie Payloads zu erfassen, entweder Enable debug mode until aktivieren (wie in Schritt 1) oder Operation debug logging mit Show Request & Response Payloads in Logs und Verbose logging kombinieren. Welche Daten jede Einstellung erfasst, hängt von der aktivierten Kombination ab; für die vollständige Aufschlüsselung siehe API-Request- und Response-Daten.
    3. Debug-Modus nach dem Erfassen der benötigten Protokolle deaktivieren, da das Aktivieren das Protokollvolumen erhöht.

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

  • Symptom: Ein Workflow, der eine API-Request-Payload mehr als 2 Tage nach dem API-Aufruf vom Agent abruft, kann die Payload nicht finden.
  • Mögliche Ursache: API-Request-Payloads für benutzerdefinierte APIs und OData-Services werden maximal 2 Tage lang auf dem Agent gespeichert. Nach diesem Zeitraum ist die Payload nur verfügbar, wenn die Operation sie bereits in einen persistenten Speicher-Connector (z. B. Temporary Storage, File Share oder eine Datenbank) geschrieben hat.
  • Lösung:
    • Gestalte Operationen, die API-Request-Payloads verarbeiten, so, dass sie die Daten sofort nach dem API-Aufruf verarbeiten, anstatt den Payload-Abruf zu verschieben.
    • Wenn die Payload für eine längere Verarbeitung beibehalten werden muss, schreibe sie in der ursprünglichen API-ausgelösten Operation an einen persistenten Speicherort.

API Logs-Seite behält vorherige Filterauswahlen 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 speichert Filterauswahlen aus der vorherigen Sitzung. Ein zuvor angewendeter Filter kann die erwarteten Ergebnisse ausblenden.
  • Lösung: Überprüfe auf der Seite API Logs alle aktiven Filter und lösche alle, die die erwarteten Einträge möglicherweise ausschließen.

Unveröffentlichte APIs werden nicht in der Analytics-APIs-Dropdown angezeigt

  • 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 derzeit veröffentlichte APIs werden in der Dropdown APIs angezeigt. APIs, die unveröffentlicht wurden, werden aus der Dropdown ausgeschlossen, auch wenn API-Protokolle für diese APIs vorhanden sind.
  • Lösung:
    • Bestätige, dass die API veröffentlicht wurde. Um Analysedaten anzuzeigen, muss sich die API in einem veröffentlichten Zustand befinden.
    • Um Protokolleinträge für eine unveröffentlichte API anzuzeigen, verwende stattdessen die Seite API Logs. Protokolldaten bleiben dort verfügbar, können aber nicht nach API-Name gefiltert werden.

Ratenbegrenzung

Fehler 429: Monatliches API-Hit-Kontingent überschritten

  • Symptom: Alle APIs in der Organisation geben plötzlich HTTP 429-Fehler zurück.
  • Mögliche Ursache: Die Organisation hat ihr monatliches API-Hit-Kontingent, das durch ihre Lizenz definiert ist, aufgebraucht. Wenn das Kontingent überschritten wird, werden alle API-Aufrufe für den Rest des Monats mit einer 429-Antwort abgelehnt.
  • Lösung:
    • Überprüfe die aktuelle Hit-Anzahl gegen dein monatliches Kontingent auf der Seite APIs. Das Kontingent wird am ersten Tag des folgenden Monats zurückgesetzt.
    • Um zu vermeiden, dass das Limit erreicht wird, konfiguriere Ratenbegrenzungen auf Umgebungs- oder Sicherheitsprofil-Ebene mit der Einstellung Hits pro Minute, um die Last zu verteilen und Verbrauchslimits pro Consumer durchzusetzen.
    • Um das monatliche Kontingent deiner Organisation zu erhöhen, kontaktiere deinen 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 dieselbe API erfolgreich aufrufen können.
  • Mögliche Ursache: Das der API zugewiesene Sicherheitsprofil 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. Öffne das Sicherheitsprofil, das der API zugewiesen ist, und überprüfe seine Konfiguration der vertrauenswürdigen IP-Gruppe.
    2. Füge die IP-Adresse oder den Adressbereich des Consumers zu einer vorhandenen vertrauenswürdigen IP-Gruppe hinzu, oder erstelle eine neue vertrauenswürdige IP-Gruppe, die die erforderlichen Adressen enthält.

Plattformweite Rate Limit: 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 Rate Limits 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 gemeinsam genutzt wird. Dieses Limit gilt nicht für private API-Gateways.
  • Lösung:
    • Überprüfen Sie Ihre API-Verkehrsmuster und verteilen Sie Aufrufe zeitlich, wenn möglich, um innerhalb des Limits von 200 Anfragen pro Minute zu bleiben.
    • Wenn Ihr Anwendungsfall einen anhaltenden Durchsatz über diesem Limit 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 sie über ein Zscaler-verwaltetes oder ähnliches SSL-inspizierendes Netzwerk weitergeleitet werden.
  • Mögliche Ursachen:
    • Zscaler und ähnliche Sicherheitsproxys führen SSL/TLS-Inspektionen durch, indem sie HTTPS-Datenverkehr abfangen und mit ihrem eigenen CA-Zertifikat neu signieren. Clientsysteme, die der Zscaler-Root-CA nicht vertrauen, lehnen die Verbindung ab.
    • Das manuelle Importieren des Jitterbit-Zertifikats in den Trust Store ist keine zuverlässige Lösung: Wenn Jitterbit sein Zertifikat erneuert, wird die manuell importierte Kopie veraltet und unterbricht die Verbindung erneut.
  • Lösung:
    • Installieren Sie das Zscaler-Root-CA-Zertifikat im Betriebssystem oder Browser-Trust Store auf den Systemen, die die API-Aufrufe durchführen, damit von Zscaler neu signierte Zertifikate vertraut werden.
    • Konfigurieren Sie Tools wie curl, wget oder openssl so, dass sie den in der Zscaler-Umgebung definierten HTTP-Proxy verwenden.
    • Fordern Sie eine Zscaler-Richtlinienausnahme für die Jitterbit-API-Gateway-Hostnamen an, um die SSL-Inspektionen für diese spezifischen Ziele zu umgehen.
    • Überprüfen Sie die Regeln der PAC-Datei (Proxy Auto-Configuration) der Organisation, um zu bestätigen, dass Jitterbit-Endpunkte korrekt verarbeitet werden.
    • Importieren Sie das Jitterbit-Leaf-Zertifikat nicht manuell in einen Trust Store als Lösung: Verwenden Sie stattdessen die Zscaler-Root-CA, um Probleme bei der Zertifikaterneurung durch Jitterbit zu vermeiden.