APIs und API Manager – Fehlerbehebung

Dieser Leitfaden behandelt häufige Fehler und Probleme, die beim Konfigurieren, Veröffentlichen und Verwenden von APIs in Jitterbit API Manager auftreten. Führen Sie zunächst die Diagnoseschritte unten aus, um Informationen zu sammeln, und suchen Sie dann nach Ihrem spezifischen Problem im entsprechenden Abschnitt.

Eine einheitliche Referenz zur Fehlerbehebung für Integration, Automatisierung, API-Verwaltung, EDI und App-Entwicklung findest du im Harmony-Fehlerbehebungsleitfaden.

• Ratenbegrenzung

  -   [Fehler 429: Monatliches API-Kontingent überschritten](#429-monthly)
  -   [Fehler 429: Consumer-IP nicht im vertrauenswürdigen IP-Bereich](#429-ip)
  -   [Plattformebene Ratenbegrenzung: 200 Anfragen pro Minute](#platform-rate-limit)
  

  • Netzwerk und Konnektivität

    • Zscaler oder SSL-abfangende Firewall blockiert API-Zugriff

Diagnoseschritte

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

API-Protokolle überprüfen

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

Um auch die vollständigen Request- und Response-Payloads zu erfassen, verwende den Debug-Modus – die beste Option für aktive Problembehebung: Er erfasst Request- und Response-Daten zusammen mit detailliertem Aktivitäts-Level-Logging und schaltet sich automatisch am von dir festgelegten Datum aus.

1. Aktiviere auf der Registerkarte Einstellungen der API-Konfiguration Debug-Modus aktivieren bis und lege ein Datum fest, um ihn aktiv zu halten. Siehe die Konfigurationsreferenz für Custom APIs, OData-Services oder Proxy-APIs.
2. Führe die Anfrage erneut aus und überprüfe dann die Payloads in den API-Protokollen.

Jitterbit-Systemstatus überprüfen

Wenn ein Problem alle APIs oder die API Manager-Schnittstelle selbst anstelle einer einzelnen API zu betreffen scheint, überprüfe die Seite Jitterbit-Systemstatus und die Seite bekannte Probleme bevor du weitere Untersuchungen durchführst.

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 fehl mit einem Fehler von Microsoft, der eine Unübereinstimmung der Reply-URL anzeigt:

  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 fehlerhaft konstruiert wird und keiner der in der Azure-App-Registrierung registrierten Reply-URLs entspricht.

• Lösung:
  1. Öffne das Sicherheitsprofil im API Manager und benenne es so um, dass alle Leerzeichen entfernt werden (ändere z. B. My Profile in MyProfile oder my-profile).
  2. Überprüfe in der Azure-App-Registrierung, dass die dort registrierten Reply-URLs dem Redirect-URI entsprechen, den der 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 wurde, stimmt nicht mit der im API Manager-Sicherheitsprofil konfigurierten Zielgruppe überein. Dies deutet normalerweise darauf hin, dass die Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder dass der OAuth-Bereich, den der Client anfordert, nicht mit der registrierten URI übereinstimmt.

• Lösung:
  1. Öffnen Sie im Azure-Portal die App-Registrierung, die diesem Sicherheitsprofil zugeordnet ist, und gehen Sie zu API verfügbar machen.
  2. Vergewissern Sie sich, dass die Application ID URI auf eine gültige URI im Format api://<Application (client) ID> eingestellt ist.
  3. Im Sicherheitsprofil überprüfen Sie, dass der OAuth-Bereich auf api://<Application (client) ID>/.default eingestellt ist.
  4. Aktualisieren Sie die Client-Anwendung, um ein Token mit diesem exakten Bereich anzufordern.
  5. Falls die Validierung weiterhin fehlschlägt, nachdem Zielgruppe und Bereich korrekt eingestellt sind, öffnen Sie das Manifest der App-Registrierung und vergewissern Sie sich, dass requestedAccessTokenVersion auf 2 eingestellt 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 funktioniert haben, schlagen mit Authentifizierungsfehlern fehl.
• Mögliche Ursache: Die App-Registrierung des Sicherheitsprofils ist noch 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 Konfiguration des Microsoft Entra ID-2-teiligen OAuth-Sicherheitsprofils befolgen.

Google oder Salesforce Identity Provider: 2-teiliges 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-teiliges OAuth konfiguriert ist.
• Mögliche Ursache: OAuth 2.0-API-Sicherheitsprofile von Google und Salesforce unterstützen 2-teiliges OAuth nicht.
• Lösung: Verwenden Sie ein 3-teiliges OAuth 2.0-Sicherheitsprofil für APIs, die sich mit Google oder Salesforce als Identitätsanbieter authentifizieren.

Microsoft Copilot Studio: Standardauthentifizierung 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 Standardauthentifizierung nicht. 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 zugeordnet ist.
  2. Ändern Sie den Authentifizierungstyp zu API-Schlüssel oder OAuth 2.0, oder entfernen Sie das Sicherheitsprofil aus der API, falls der Endpunkt keine Authentifizierung erfordert.
  3. Veröffentlichen Sie die API erneut und verbinden Sie sie dann in Microsoft Copilot Studio erneut. Siehe Jitterbit-KI-Agent mit Microsoft Copilot Studio verbinden.

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

• Symptom: Die Schaltfläche Neue API wird im API Manager für einen Benutzer nicht angezeigt, der eine Rolle auf Organisationsebene hat, aber kein Organisationsadministrator ist. Wenn man dem Benutzer die Berechtigung Admin auf Organisationsebene gewährt, wird die Schaltfläche zwar angezeigt, macht aber auch alle Umgebungen für den Benutzer sichtbar.
• Mögliche Ursache: Eine Rolle auf Organisationsebene allein reicht nicht aus, um APIs zu erstellen. Die Rolle muss auch Schreibzugriff auf Umgebungsebene für die spezifische Umgebung haben, in der der Benutzer APIs erstellen muss.
• Lösung:
  1. Wechseln Sie in der Management Console zu Umgebungen und öffnen Sie die Umgebung, in der der Benutzer APIs erstellen muss.
  2. Bestätigen Sie, dass für die Rolle des Benutzers in dieser Umgebung der Schreibzugriff aktiviert ist. Ist das nicht der Fall, aktivieren Sie ihn und speichern Sie.
  3. Die Schaltfläche Neue API sollte jetzt für diese Umgebung sichtbar sein.

Basic Auth: Anmeldedaten aus dem Cache eines früheren Requests beeinflussen einen späteren API-Aufruf

• Symptom: Anmeldedaten für die Basic-Authentifizierung aus dem Cache eines früheren Requests können einen späteren API-Aufruf auf eine der folgenden Arten beeinflussen:

  • Eine API mit zwei oder mehr zugewiesenen Basic-Auth-Sicherheitsprofilen zeigt in den API-Protokollen unerwartete Benutzernamen an, darunter Benutzernamen, die keinem der Profile angehören. Einige Anfragen schlagen mit einem Fehler 401 Unauthorized fehl.
  • Eine Proxy-API oder ein OData-Service mit einem zugewiesenen Basic-Auth-Sicherheitsprofil gibt eine erfolgreiche Antwort zurück, ohne zur Eingabe von Anmeldedaten aufzufordern.

• Mögliche Ursache: Der Browser oder API-Client (z. B. Postman) hat Basic-Auth-Anmeldedaten aus einer früheren Sitzung als Cookie im Cache gespeichert. Wenn die API erneut aufgerufen wird, sendet der Client zunächst den im Cache gespeicherten Cookie. Wenn die zwischengespeicherten Anmeldedaten 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 Aufforderung angezeigt wird.

• Lösung:

  1. Löschen Sie vor erneutem Testen der API die Cookies und den Cache des Browsers, oder wechseln Sie zu einem Inkognito- oder privatem Browserfenster.
  2. Bestätigen Sie, dass das Verhalten nicht vorhanden ist, wenn eine neue Anfrage ohne vorherige Sitzungs-Cookies gestellt wird. Wenn das Verhalten verschwindet, handelt es sich um clientseitiges Zwischenspeichern von Anmeldedaten und nicht um ein Konfigurationsproblem.

  Beachten Sie, dass jeder HTTP-Client, der Cookies speichert (einschließlich browsergestützter Tools und API-Testprogramme), das gleiche Verhalten aufweisen kann.

Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG

• Symptom: Ein API-Aufruf mit einem Sicherheitsprofil mit Basic-Authentifizierung oder einer benutzerdefinierten Protokollierung schlägt mit einem Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG fehl, obwohl die gleichen Anmeldedaten oder der gleiche 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-Authentifizierung mit der Standard-Protokollierung ist dieser Wert das Feld Benutzername des Sicherheitsprofils.
  • Bei einer benutzerdefinierten Protokollierung ist es der Wert, den die aufrufende Anwendung im konfigurierten Header sendet.

Character Validation 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 auftreten, obwohl sich die Konfiguration des Sicherheitsprofils nicht geändert hat.

Ab der 12.12 Harmony-Version lehnt das Feld Benutzername des Sicherheitsprofils die nicht zulässigen Zeichen ab. Es ist daher nicht mehr möglich, ein Sicherheitsprofil zu speichern, das diese enthält. Für Basic-Authentifizierung mit der standardmäßigen Protokollierungseinstellung gilt INVALID_TRIGGER_USER daher nur für Sicherheitsprofile, die vor dieser Version gespeichert wurden.

• Lösung:
  • Für Basic-Authentifizierung mit der standardmäßigen Protokollierungseinstellung: 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, je nach Bedarf. Aktualisieren Sie dann die Anmeldedaten in jeder aufrufenden Anwendung, die den vorherigen Benutzernamen referenziert.
  • Für eine Custom-Protokollierungseinstellung: 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 ist.

401 Unauthorized bei gültiger IP-Allowlist (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 Einträgen des alten IP-Bereichs im Sicherheitsprofil überschreibt die aktiven vertrauenswürdigen IP-Gruppen.
• Lösung: Migrieren Sie das Sicherheitsprofil von alten IP-Bereichen zum Modell Vertrauenswürdige IP-Gruppen, dem aktuellen Allowlist-Mechanismus: 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 bei einem Profil, das noch ältere IP-Bereiche verwendet, entfernt diese Bereiche dauerhaft (eine Bestätigungsmeldung warnt davor). Migrieren Sie die IPs daher zu einer vertrauenswürdigen IP-Gruppe, anstatt die Einstellung auszuschalten, um den Cache zu leeren.

Salesforce on Hyperforce: Callouts zu einer API werden nach Änderung der Salesforce-IP-Adressen abgelehnt

• Symptom: Callouts von Salesforce zu einer API (ausgehende Nachrichten, Apex-Callouts, Salesforce Connect oder aufrufbare Aktionen) werden nach der Migration der Salesforce-Organisation zu Hyperforce, Salesforces öffentlicher Cloud-Infrastruktur, abgelehnt. 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 ordnen die Quell-IP-Adresse einer Anfrage zu, und die Adressen, die eine Salesforce-Organisation auf Hyperforce für ausgehende Callouts verwendet, ändern sich im Laufe der Zeit. Eine Gruppe, die einen festen Satz von Salesforce-Adressen auflistet, passt nicht mehr.

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

  1. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und setzen Sie seinen Authentifizierungstyp auf API Key. Konfigurieren Sie den Salesforce-Callout so, dass der Schlüssel in einem Request-Header gesendet wird, nicht in einem Abfrageparameter, damit er nicht in Request-URLs aufgezeichnet wird. OAuth 2.0 ist auch verfügbar, obwohl mit Salesforce als Identitätsanbieter der einzige Flow 3-legged ist, was manuelle Interaktion erfordert.

• Nachdem der Callout erfolgreich authentifiziert wurde, 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 zu deaktivieren, was dauerhaft alle noch auf dem Profil gespeicherten Legacy-IP-Bereiche entfernt.

Wenn 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. Die Allowlist aktuell zu halten bedeutet daher, die Datei zu verfolgen und die vertrauenswürdige IP-Gruppe entsprechend zu aktualisieren. Callouts von einer Adresse, die hinzugefügt wurde, nachdem die Gruppe zuletzt aktualisiert wurde, werden abgelehnt. Diese Adressen werden auch organisationsübergreifend bei Salesforce freigegeben, sodass das Allowlisten dieser Adressen bestätigt, woher eine Anfrage stammt, nicht, dass sie von Ihrer Organisation stammt. 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: 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 veröffentlichter API-URLs erreicht, die das Abonnement zulässt. Jede veröffentlichte Custom API, jeder OData-Service oder jede Proxy-API (und jeweils ihre veröffentlichten Klone) nutzt eine API-URL. Entwurf-APIs werden nicht mitgezählt.

• Lösung: Überprüfen Sie auf der Seite APIs des API Managers die Anzahl Custom API URLs used (genutzte Custom-API-URLs) und Proxy API URLs used (genutzte Proxy-API-URLs), die oben auf der Seite angezeigt werden, gegen die Gesamtzahl, die Ihr Abonnement zulässt. Heben Sie die Veröffentlichung nicht mehr benötigter APIs auf oder löschen Sie diese, 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: Der Aufruf einer veröffentlichten API gibt einen 404-Fehler zurück.
• Mögliche Ursachen:
  • Das Limit Hits per minute (Hits pro Minute) im zugewiesenen Sicherheitsprofil ist auf null gesetzt, was alle Anfragen blockiert. Eine Änderung der Abonnementebene der Organisation kann dieses Limit zurücksetzen, sodass eine API, die zuvor funktioniert hat, beginnen kann, 404s zurückzugeben.
  • Die Konfiguration, die Basis-URL oder die Sichtbarkeitseinstellungen der API sind fehlerhaft.
  • 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 per minute auf eine Zahl ungleich null gesetzt ist. Wenn das Limit kürzlich zurückgesetzt wurde (beispielsweise nach einer Abonnementänderung), stellen Sie es auf den beabsichtigten Wert wieder her.
  • Überprüfen Sie auf der Seite APIs, dass die API erfolgreich veröffentlicht wurde und dass 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:
  • Reduziere die Länge der Service-URL, indem du den Service-Pfad verkürzest oder die API in mehrere Endpunkte aufteilst.
  • Überprüfe bei Proxy-APIs, dass die Kombination aus Basis-URL und allen definierten Service-Pfaden das 8.000-Zeichen-Limit nicht überschreitet.

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

• Symptom: Die Konfiguration eines Proxy-API-Service-Pfads mit Pfadparametern (beispielsweise /resource/{id}) schlägt fehl, wenn man diese manuell eingibt, 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, stelle ein OpenAPI-Dokument bereit, das die Pfade und ihre Parameter definiert. 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 eine generische Fehlermeldung an und die API wird nicht entfernt. Der Fehler tritt im Browser auf, bevor eine Löschanforderung den Server erreicht, und wird in der Browser-Entwicklerkonsole als JavaScript-TypeError angezeigt.
• Mögliche Ursache: Die Rolle des Benutzers verfügt nicht über die Berechtigung Admin. Beim Löschen einer API wird zunächst überprüft, welche API-Gruppen der API zugeordnet sind. Das Anzeigen der Seite API-Gruppen erfordert die Berechtigung Admin: Eine Rolle mit nur Write-Umgebungszugriff kann die Seite öffnen, kann aber deren Inhalte nicht 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: Lasse einen Benutzer, dessen Rolle die Berechtigung Admin Rollenberechtigung hat, das Löschen durchführen. Das Erteilen der Berechtigung Admin für die betroffene Rolle funktioniert ebenfalls, aber das ist eine umfassende Erhöhung auf Organisationsebene. Bevorzuge daher, 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 Feld Umgebung ist nicht bearbeitbar.
• Mögliche Ursache: Die Umgebung wird bei der API-Erstellung festgelegt und kann danach nicht geändert werden.
• Lösung:
  • Um eine benutzerdefinierte oder Proxy-API in eine andere Umgebung zu verschieben, klone die API von der Seite APIs und wähle während des Klonens die richtige Umgebung.
  • Alternativ kannst du die API aus ihrer aktuellen Umgebung exportieren und in die Zielumgebung importieren.

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

• Symptom: Nach der Aktivierung von CORS auf einer benutzerdefinierten oder Proxy-API verarbeitet die HTTP-Methode OPTIONS Anfragen ohne Authentifizierung.
• Mögliche Ursache: Die Aktivierung von CORS führt dazu, dass Operationen mit der Methode OPTIONS ohne Authentifizierung ausgeführt werden. Dies ist erforderlich, um Preflight-Anfragen von Browsern zu unterstützen, bedeutet aber auch, dass jede OPTIONS-Anfrage die Operation erreicht, ohne ein Sicherheitsprofil zu durchlaufen.
• Lösung:
  • Wenn die API OPTIONS nicht für vertrauliche Operationen nutzt, ist keine Aktion erforderlich. Dies ist das erwartete Verhalten, wenn CORS aktiviert ist.
  • Falls eine authentifizierte Behandlung von OPTIONS erforderlich ist, deaktiviere CORS auf der API oder strukturiere die Operation so um, dass sie unauthentifizierte Preflight-Anfragen explizit erkannt und bearbeitet.

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

• Symptom: Eine Proxy-API, die das von Jitterbit gehostete Cloud-API-Gateway nutzt, gibt Fehler zurück oder kann die Ziel-API nicht erreichen.
• Mögliche Ursache: Bei Verwendung des Cloud-API-Gateways muss die zu proxying-betreibende 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 selben privaten Netzwerk bereit, anstatt das Cloud-API-Gateway zu verwenden.
  • Um die IP-Adressen des Cloud-Gateways auf die Zulassungsliste zu setzen, damit das Gateway auf die Proxy-API zugreifen kann, siehe Informationen zur Zulassungsliste.

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

• Symptom: Der Toggle Request & Response Payloads in Logs anzeigen erscheint in den Einstellungen einer Proxy-API, aber das Aktivieren hat keine Auswirkung auf die Log-Ausgabe.
• Mögliche Ursache: Request- und Response-Payload-Protokollierung wird für Proxy-APIs nicht unterstützt. Der Toggle 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 Endpoint aufruft, wobei die Einstellung Request & Response Payloads in Logs anzeigen unterstützt wird.

Leistung und Timeouts

HTTP 504 Gateway Timeout

• Symptom: API-Aufrufe geben folgende Fehlermeldung 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 formatiert oder Path-Parameter 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, um innerhalb des Gateway-Timeout-Fensters zu antworten, 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, weshalb sie beim Gateway auslöst, bevor der Betrieb ausgeführt wird. Ein Zeichen dafür ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Betriebsprotokollen hat.

• Lösung:

  • Überprüfen Sie, dass die API-URL korrekt formatiert ist. Falls die API Path-Parameter verwendet, sollten Sie erwägen, dem Betrieb ein Skript hinzuzufügen, das die URL explizit analysiert und die Parameterwerte erfasst.
  • Wenn das Timeout durch einen langsamen Backend verursacht wird, überprüfen Sie den Betrieb und seine Transformationslogik auf Performance-Engpässe, besonders große Datenmengen oder langsame externe Aufrufe, und reduzieren Sie den langsamen Schritt.
  • Falls der Betrieb zeitlich mehr benötigt als die aktuelle Einstellung erlaubt, erhöhen Sie das Timeout auf der API-Einstellungsregisterkarte. 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.
  • Falls der Betrieb nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeitantwort nicht erforderlich ist, gestalten Sie den Betrieb der API so um, dass die langwierige Arbeit asynchron gestartet wird (beispielsweise durch Aufrufen mit RunOperation im asynchronen Modus), damit die API eine Antwort zurückgeben kann, ohne auf deren Abschluss zu warten. Siehe Asynchrone Operationen verwalten.
  • Für gelegentliche Timeouts fügen Sie Wiederholungen hinzu, um transiente Fehler erneut zu versuchen: 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 Agent-Last korrelieren, überprüfen Sie die Agent-Kapazität: Führen Sie API-verwaltende Operationen auf Agents getrennt von schweren ETL-Workloads aus und fügen Sie der Gruppe Agents hinzu, wenn diese überlastet ist. Siehe Optimieren und verbessern Sie die Leistung von Jitterbit Private Agents.

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

• Symptom: Anfragen über ein privates API-Gateway schlagen zeitweilig mit einer HTTP-400-Antwort fehl. Der Aufrufer erhält statt einer normalen API-Antwort 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-Protokollen für die fehlgeschlagene Anfrage, da die Anfrage nie eine 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 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 mehr Agents zur Agent-Gruppe 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 Fehler erschöpft sind.
  3. Wenn die Agents auch nach einer Skalierung durchgehend aus Apache-Worker-Threads ausgelastet sind, wenden Sie sich an den Jitterbit-Support, um die Apache-Worker-Thread-Kapazität der Agents zu überprüfen (die MaxRequestWorkers-Einstellung). Ändern Sie die Jitterbit-Apache-Konfigurationsdateien nicht, wenn dies nicht vom Jitterbit-Support angewiesen wird. 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 auf dem 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 Sicherheitsprofilkonfiguration aktiv ist, selbst 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 noch auftritt, 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 auf dem 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:
  • Öffnen Sie nach dem Löschen einer API 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 einem 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 einem API entfernt wurde.
• Mögliche Ursache: Nachdem ein Sicherheitsprofil aus der API-Konfiguration entfernt wurde, muss das API gespeichert und erneut veröffentlicht werden, bevor das Profil als vollständig entfernt gilt. Bis das API erneut veröffentlicht wird, behandelt API Manager das Profil weiterhin als aktiv.
• Lösung:
  1. Nachdem das Sicherheitsprofil vom API entfernt wurde, klicken Sie auf Speichern und dann auf Veröffentlichen.
  2. Sobald das API mit der aktualisierten Konfiguration erneut veröffentlicht wurde, zeigt das Sicherheitsprofil nicht mehr an, dass es aktiv ist, und kann gelöscht werden.

Probleme mit privaten Gateways

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

• Symptom: Ein Sicherheitsprofil, das für 2-Legged-OAuth konfiguriert ist, nutzt stattdessen 3-Legged-OAuth, wenn es über ein privates API-Gateway bereitgestellt wird.
• Mögliche Ursache: Private API-Gateways mit einer Version früher 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. Überprüfen Sie die Version des privaten API-Gateways, das das 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 auf dem gleichen Host ausgeführt werden

• 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 die einzelnen Gateways den Anschein machen, fehlerfrei zu sein.
• Mögliche Ursache: Bei Verwendung eines containerisierten privaten API-Gateways mit einem ALB müssen alle Gateway-Container auf der gleichen Host-Maschine ausgeführt werden. Container, die auf verschiedenen Hosts bereitgestellt werden, können die Payload-Abrufung nicht koordinieren, was zu zeitweisen Fehlern führt.
• Lösung:
  1. Bestätigen Sie, dass alle privaten API-Gateway-Container in der Gruppe auf dem gleichen physischen oder virtuellen Host ausgeführt werden.
  2. Wenn Container auf mehrere Hosts verteilt sind, konsolidieren Sie diese auf einem einzelnen Host.
  3. Für Multi-Host-Bereitstellungen überprüfen Sie die ALB-Konfiguration im Gateway-Installationsleitfaden auf weitere Konfigurationsanforderungen.

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

• Symptom: Nach einem 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. Erstellen Sie vor dem Upgrade des privaten API-Gateways eine Sicherungskopie der On-Premise-Konfigurationsdatei.
  2. Nach Abschluss des Upgrades wenden Sie Ihre benutzerdefinierten SSL-Einstellungen auf die neue Konfigurationsdatei an.

Private Gateway gibt HTTP 507 oder „No such file or directory" 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
  

  auch wenn auf den Gateway-Hosts ausreichend Speicherplatz verfügbar 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 Speicherplatz mehr hat. In 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 für jeden Node sind.

• Lösung:

  1. Bestätigen Sie, dass die Gateway-Hosts nicht wirklich keinen Speicherplatz mehr haben, indem Sie die Festplatte und 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. Falls das Gateway als mehrere Nodes hinter einem Load Balancer ausgeführt wird, bestätigen Sie, dass der Load Balancer jede Anfrage und deren Antwort konsistent zum gleichen Node leitet, da gehostete Payload- und Antwortdateien lokal für den Node sind, der sie erstellt hat. Für Container-Gateways siehe Multi-Gateway ALB: Alle Container müssen auf demselben Host sein.
  3. Falls der Fehler weiterhin auftritt, 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 sowie der ls -lR-Ausgabe für die hosted-files-Verzeichnisse auf jedem Node. Der Support kann serverbasierte Bedingungen überprü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 fehl mit fehlenden Abhängigkeiten

• Symptom: Das Ausführen von yum install zum Installieren oder Upgraden eines Linux-Private-API-Gateways (RPM) auf Version 10.62 oder später schlägt mit fehlenden Abhängigkeitsfehlern 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 von der 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 Internetzugriff hat und EPEL nicht erreichen kann, um die Pakete herunterzuladen.

• Lösung:

  • Aktivieren Sie auf einem Gateway-Host mit Internetzugriff die EPEL-Repository vor der Installation des Gateways, wie beschrieben in Installieren Sie ein Private-API-Gateway: 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 Internetzugriff wird durch die Installation des epel-release-Pakets allein nur die Repository-Definition hinzugefügt; die Pakete geoip-devel und libGeoIP werden nicht heruntergeladen. Laden Sie auf einem Computer mit Internetzugriff 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 „Failure, test call to API failed" zurück

• Symptom: Das Befehlszeilen-Selbsttest-Hilfsprogramm des Private-API-Gateways gibt Folgendes zurück:

  Failure, test call to API failed
  

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

• Lösung:
  • Führen Sie ein Upgrade des Private-API-Gateways auf Version 11.31 oder später durch, um dies automatisch zu beheben.
  • Falls 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 aus (z. B. service), setzen Sie Path auf /, speichern und veröffentlichen Sie, führen Sie dann das Selbsttest-Hilfsprogramm 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 Private Agents 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 werden durch Unterstriche ersetzt

• Symptom: Eine Proxy-API-Operation erhält Request-Header, bei denen Bindestriche durch Unterstriche ersetzt werden (z. B. kommt X-Custom-Header als X_Custom_Header an), was dazu führt, dass Header-Abfragen 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 sie auf false gesetzt haben, was die Ersetzung verursacht.
• Lösung:
  • In der Proxy-API-Konfiguration die Header-Einstellung disable-hyphen-replacement überprüfen. Um Bindestriche in Header-Namen beizubehalten, die Einstellung auf true stellen.
  • Wenn 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 für API-gesteuerte Operationen nicht sichtbar, wenn der Debug-Modus deaktiviert ist

• Symptom: Nach dem Aufrufen einer API zeigt das API-Protokoll an, dass der Aufruf erfolgreich war, aber auf der Seite Runtime ist kein Operationsprotokoll für die von der API ausgelöste Operation sichtbar. Aufrufe von WriteToOperationLog aus der Operation heraus 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. Fehlerhafte 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 rohen Request- und Response-Daten sowie Nutzlasten zu erfassen, entweder Enable debug mode until aktivieren (wie in Schritt 1) oder Operation debug logging mit beiden Show Request & Response Payloads in Logs und Verbose logging kombinieren. Welche Daten jede Einstellung erfasst, hängt von der aktivierten Kombination ab; eine vollständige Übersicht finden Sie unter 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 verfügbar auf Agent für 2 Tage

• Symptom: Ein Workflow, der eine API-Request-Payload vom Agent mehr als 2 Tage nach dem API-Aufruf abruft, kann die Payload nicht finden.
• Mögliche Ursache: API-Request-Payloads für benutzerdefinierte APIs und OData-Services werden maximal 2 Tage auf dem Agent gespeichert. Nach diesem Zeitraum ist die Payload nur verfügbar, wenn die Operation sie bereits in einen persistenten Storage-Connector (wie Temporary Storage, File Share oder eine Datenbank) geschrieben hat.
• Lösung:
  • Gestalten Sie Operationen so, dass sie API-Request-Payloads unmittelbar bei dem API-Aufruf verarbeiten, anstatt den Payload-Abruf zu verschieben.
  • Wenn die Payload für längere Verarbeitung beibehalten werden muss, schreiben Sie sie in der initial API-gesteuerten Operation in einen persistenten Storage-Ort.

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 verbergen.
• Lösung: Überprüfen Sie auf der Seite API Logs alle aktiven Filter und löschen Sie alle, die die erwarteten Einträge möglicherweise ausschließen.

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

• Symptom: Eine API wird nicht in der Dropdown-Liste 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 werden in der Dropdown-Liste APIs angezeigt. APIs, die nicht veröffentlicht wurden, werden in der Dropdown-Liste 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 sich die API in einem veröffentlichten Zustand befinden.
  • 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.

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 gemäß ihrer Lizenz ausgeschöpft. Wenn das Kontingent überschritten wird, werden alle API-Aufrufe für den Rest des Monats mit einer 429-Antwort abgelehnt.
• Lösung:
  • Überprüfen Sie die aktuelle Hit-Anzahl gegen Ihr monatliches Kontingent auf der APIs-Seite. Das Kontingent wird am ersten Tag des folgenden Monats zurückgesetzt.
  • Um die Grenze zu vermeiden, konfigurieren Sie Ratenbegrenzungen auf Umgebungs- oder Sicherheitsprofilleene mit der Einstellung Hits pro Minute, um die Last zu verteilen und Verbrauchsgrenzen pro Consumer durchzusetzen.
  • Um das monatliche Kontingent Ihrer Organisation zu erhöhen, wenden Sie sich an 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 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. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und überprüfen Sie die Konfiguration seiner vertrauenswürdigen IP-Gruppe.
  2. Fügen Sie die IP-Adresse oder den Adressbereich des Consumers zu einer bestehenden vertrauenswürdigen IP-Gruppe hinzu, oder erstellen Sie 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, selbst 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) verteilt ist. Dieses Limit gilt nicht für private API-Gateways.
• Lösung:
  • Überprüfe die API-Verkehrsmuster und verteile Aufrufe zeitlich, falls möglich, um das Limit von 200 Anfragen pro Minute einzuhalten.
  • Falls der Anwendungsfall einen anhaltenden Durchsatz über diesem Limit erfordert, stelle 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 durch ein von Zscaler verwaltetes oder ähnliches SSL-inspizierendes Netzwerk geleitet werden.
• Mögliche Ursachen:
  • Zscaler und ähnliche Sicherheitsproxys führen SSL/TLS-Inspektionen durch, indem sie HTTPS-Datenverkehr abfangen und ihn 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 Vertrauensspeicher ist keine zuverlässige Lösung: Wenn Jitterbit sein Zertifikat erneuert, wird die manuell importierte Kopie veraltet und unterbricht die Verbindung erneut.
• Lösung:
  • Installiere das Zscaler-Root-CA-Zertifikat im Betriebssystem oder Browser-Vertrauensspeicher auf den Systemen, die die API-Aufrufe durchführen, damit von Zscaler neu signierte Zertifikate vertraut wird.
  • Für Tools wie curl, wget oder openssl konfiguriere diese so, dass sie den im Zscaler-Umfeld definierten HTTP-Proxy verwenden.
  • Fordere eine Zscaler-Richtlinienausnahme für die Jitterbit-API-Gateway-Hostnamen an, um die SSL-Inspektion für diese spezifischen Ziele zu umgehen.
  • Überprüfe die Regeln in der PAC-Datei (Proxy Auto-Configuration) der Organisation, um zu bestätigen, dass Jitterbit-Endpunkte korrekt verarbeitet werden.
  • Importiere das Jitterbit-Blatt-Zertifikat nicht manuell als Lösung in einen Vertrauensspeicher: Verwende stattdessen die Zscaler-Root-CA, um Probleme bei der Zertifikaterneurung durch Jitterbit zu vermeiden.