Fehlerbehebung bei der Datenexport-API
Nutzen Sie diesen Abschnitt, um häufige Fehlermeldungen der Datenexport-API zu interpretieren
und für jede einzelne die wahrscheinlichste Ursache sowie die entsprechende Abhilfe
zu ermitteln. Jede Fehlermeldung enthält einen
code, eine message und einen numerischen statusCode; der code-Wert gibt die jeweilige Bedingung an.Fehler bei der Authentifizierung und Autorisierung
| Fehlercode | Mögliche Ursache | Was Sie ausprobieren sollten |
|---|---|---|
ERR_INVALID_APIKEY (401) |
Die Kopfzeile x-api-key fehlt, ist fehlerhaft, abgelaufen oder wurde gelöscht. Tritt zudem kurzzeitig (in
der Regel weniger als eine Minute) unmittelbar nach der Erstellung oder Rotation eines
Schlüssels auf, bevor der neue Schlüssel registriert wird. |
Bitte stellen Sie sicher, dass die Anfrage die Kopfzeile x-api-key mit dem vollständigen Schlüsselwert enthält. Überprüfen Sie unter Account Administration, ob der Schlüssel noch vorhanden ist und nicht abgelaufen ist. Falls der Schlüssel
gerade erst erstellt oder rotiert wurde, warten Sie bitte eine Minute und versuchen
Sie es dann erneut. |
ERR_UNAUTHORIZED_PRINTERS (403) |
Die Anfrage enthält einen oder mehrere printerId-Werte, auf die der API-Schlüssel keinen Zugriff hat. |
Rufen Sie den Befehl /printers mit demselben API-Schlüssel auf, um genau zu sehen, welche Drucker verfügbar sind,
und senden Sie die Anfrage anschließend erneut, wobei Sie nur diese Drucker-IDs angeben. |
ERR_TENANT_NOT_FOUND (404) |
Der API-Schlüssel wird erkannt, ist jedoch keinem aktiven Konto zugeordnet. Dies kann passieren, wenn ein Konto entfernt wurde oder falsch konfiguriert ist. | Wenden Sie sich bitte an Ihren Ricoh-Kundenbetreuer, um zu überprüfen, ob Ihr Mandant aktiv ist und ob der API-Schlüssel diesem zugeordnet ist. |
Fehler bei der Parameterüberprüfung (400 Bad Request)
Jeder Fehler bei der Parameterüberprüfung führt zur Rückgabe des Statuscodes 400.
Der code-Wert gibt das konkrete Problem an.
| Fehlercode | Mögliche Ursache | Was Sie ausprobieren sollten |
|---|---|---|
ERR_MISSING_PRINTER_ID |
Die Anfrage enthielt keine printerId-Werte. Für /Jobs, /printer-states und /printer-interventions ist mindestens einer erforderlich. |
Fügen Sie mindestens einen Abfrageparameter printerId hinzu. Wiederholen Sie die Angabe des Parameters, um mehrere Drucker einzubeziehen. |
ERR_INVALID_PRINTER_ID_FORMAT |
Der Wert printerId ist keine gültige UUID. |
Vergleichen Sie den Wert mit der Antwort von /printers. Zu den häufigsten Fehlern zählen überflüssige Leerzeichen, fehlende Zeichen oder
das Einfügen des Druckernamens anstelle der Drucker-ID. |
ERR_INVALID_TIMEZONE |
Der Wert für die timezone fehlt oder ist keine gültige IANA-Zeitzonenkennung. |
Verwenden Sie eine Bereichs-Kennung wie America/Denver oder Europe/Bucharest. Dreistellige Abkürzungen wie MST oder EST werden nicht akzeptiert. Auf der interaktiven Dokumentationsseite gibt es eine Liste
aller zulässigen Werte. |
ERR_INVALID_DATE_FORMAT |
Ein Wert für startDateTime oder endDateTime ist nicht übereinstimmend mit dem erwarteten Format. |
Verwenden Sie das Format JJJJ-MM-TTTHH:MM:SS, optional mit dem Suffix .sss für Millisekunden. Geben Sie keinen UTC-Versatz und kein Z-Suffix an; die Zeitzone wird separat im Parameter timezone angegeben. |
ERR_INVALID_DATE_RANGE |
startDateTime ist gleich oder später als endDateTime. |
Bitte überprüfen Sie, ob startDateTime in der angegebenen Zeitzone vor endDateTime liegt. |
ERR_DATE_RANGE_EXCEEDED |
Der Zeitraum zwischen startDateTime und endDateTime überschreitet den maximal zulässigen Bereich. |
Verringern Sie die Dauer des angeforderten Zeitfensters. Anleitungen zur Chunking-Methode finden Sie unter Umgang mit den Antwortbeschränkungen der Datenexport-API. |
ERR_INVALID_JOB_STATE |
Der Wert jobState gehört nicht zu den zulässigen Werten. |
Verwenden Sie eine der folgenden Optionen: printing, printed, aborted oder completed. Anmerkung: Der Begriff completed umfasst sowohl printed als auch aborted Jobs. |
ERR_INVALID_STATE_CATEGORY |
Der Wert stateCategory gehört nicht zu den zulässigen Werten. |
Verwenden Sie eine der folgenden Optionen: up, down oder idle. |
ERR_INVALID_LANGUAGE |
Der an /printer-interventions übergebene language gehört nicht zu den zulässigen Werten. |
Bitte wählen Sie eine der folgenden Sprachen aus: en, de, ja, it, fr oder es. Dieser Fehler bedeutet, dass der Code selbst abgelehnt wurde; ein Code, der zwar
akzeptiert wird, für den jedoch keine Übersetzung für eine bestimmte Beschreibung
vorliegt, führt nicht zu einem Fehler, da die API diese Beschreibung stattdessen auf
Englisch zurückgibt. |
ERR_INVALID_BOOLEAN_PARAM |
Der Parameter currentState oder stateCategoryOnly hat einen anderen Wert als true oder false. |
Verwenden Sie die wörtlichen Zeichenfolgen true oder false in Kleinbuchstaben. |
ERR_UNKNOWN_PARAMETERS |
Die Anfrage enthält einen oder mehrere Parameter, die der Endpunkt nicht akzeptiert. | Vergleichen Sie die Anfrage mit den Parametern, die in der interaktiven Dokumentation für den Endpunkt auf einer Liste aufgeführt sind. Häufige Ursachen sind Tippfehler, Parameter, die für einen anderen Endpunkt bestimmt sind, oder zusätzliche Tracking-Parameter, die von einem HTTP-Client hinzugefügt wurden. |
ERR_DUPLICATE_PARAMETERS |
Derselbe Parameter wird mehrmals übergeben, und der Endpunkt akzeptiert keine Duplikate für diesen Parameter. | Bitte überprüfen Sie die Liste der Parameter. Der Parameter printerId darf wiederholt werden (einmal pro Drucker); andere Parameter dürfen höchstens einmal
vorkommen. |
ERR_EMPTY_PARAMETERS |
Ein obligatorischer Parameter ist vorhanden, weist jedoch keinen Wert auf. | Stellen Sie sicher, dass jeder erforderliche Parameter einen Wert enthält. |
ERR_INVALID_TENANT_ID |
Die dem API-Schlüssel zugeordnete Mandanten-ID ist ungültig. | Wenden Sie sich bitte an Ihren Ricoh-Kundenbetreuer. |
Fehler bei der Antwortlänge und bei der Methode
| Fehlercode | Mögliche Ursache | Was Sie ausprobieren sollten |
|---|---|---|
ERR_RESPONSE_LIMIT_EXCEEDED (413) |
Die Daten, die mit der Anfrage übereinstimmen, würden die maximale Antwortgröße überschreiten.
Der Antworttext enthält ein Feld maxJobs, das die aktuell geltende Obergrenze angibt. |
Grenzen Sie den Datumsbereich ein, geben Sie eine geringere Anzahl an Druckern an oder beides, und reichen Sie die Anfrage erneut ein. Empfohlene Chunking-Muster finden Sie unter Umgang mit den Antwortbeschränkungen der Datenexport-API. |
ERR_UNSUPPORTED_METHOD (405) |
Bei der Anfrage wurde eine andere HTTP-Methode als GET verwendet. |
Die Datenexport-API unterstützt ausschließlich die GET-Methode. Aktualisieren Sie Ihren Client, damit er GET verwendet. |
Serverfehler (500 Interner Serverfehler)
500 Antworten deuten auf eine unerwartete Bedingung auf dem Server hin. Wiederholungsversuche
sind sicher, da jeder Endpunkt der Datenexport-API ein GET-Aufruf ist und keine Nebenwirkungen verursacht. Warten Sie einige Sekunden, bevor
Sie es erneut versuchen, und wenden Sie ein exponentielles Backoff an, falls der Fehler
weiterhin auftritt.
| Fehlercode | Mögliche Ursache | Was Sie ausprobieren sollten |
|---|---|---|
ERR_INTERNAL_SERVER_ERROR |
Auf dem Server ist eine unerwartete Bedingung aufgetreten. | Bitte warten Sie einige Sekunden und versuchen Sie es erneut. Sollte der Fehler länger als einige Minuten bestehen bleiben, wenden Sie sich bitte an Ihren RICOH-Kundenbetreuer. |
ERR_TENANT_CHECK_FAILED |
Der Server konnte den mit dem API-Schlüssel verknüpften Mandanten nicht überprüfen. | Bitte warten Sie einige Sekunden und versuchen Sie es erneut. Sollte der Fehler weiterhin bestehen, wenden Sie sich bitte an Ihren Ricoh-Kundenbetreuer. |
ERR_PRINTERS_FETCH_FAILED |
Der Server konnte die Liste der Drucker für den Mandanten nicht abrufen. | Bitte warten Sie einige Sekunden und versuchen Sie es erneut. Sollte der Fehler weiterhin bestehen, wenden Sie sich bitte an Ihren Ricoh-Kundenbetreuer. |
ERR_PRINTER_STATES_FETCH_FAILED |
Der Server konnte die Druckerstatusdaten für die Anfrage nicht abrufen. | Bitte warten Sie einige Sekunden und versuchen Sie es erneut. Sollte der Fehler weiterhin bestehen, wenden Sie sich bitte an Ihren Ricoh-Kundenbetreuer. |
Weitere Symptome
- Die Antwort ist leer (
[]), doch Sie erwarten Daten - Ein leeres Array bedeutet, dass keine Datensätze mit der Anfrage übereinstimmten.
Überprüfen Sie das Zeitfenster (die API liefert nur Daten der letzten sieben Tage),
die Zeitzone, die
printerId-Werte sowie etwaige Filter wiejobStateoderstateCategory. - Die Datums- und Zeitangaben in der Antwort sind nicht übereinstimmend mit Ihren Erwartungen
- Die Zeitstempel der Antworten entsprechen der Ortszeit in der mit der Anfrage angegebenen
Zeitzone. Wird dieselbe Anfrage mit einem anderen
timezonegesendet, werden unterschiedliche Zeitstempel-Zeichenfolgen erzeugt, obwohl sie dieselben Ereignisse beschreiben. Siehe Umgang mit Datum und Uhrzeit in der Datenexport-API. - In der Antwort unter
/printersfehlt ein Drucker - Die API gibt ausschließlich Drucker zurück, die von einem Data Collector überwacht werden. Sollte ein Drucker fehlen, überprüfen Sie bitte, ob dieser bei einem Data Collector registriert wurde und derzeit eine Verbindung hat.
- Eine Antwort zu den Druckerstatus enthält
unbekannteKategorien - Eine
unknownKategorie bedeutet, dass der Rohzustand des Druckers nicht klassifiziert werden konnte. Die vollständige Zuordnung von Zuständen zu Kategorien finden Sie unter Druckerzustände und Zustandskategorien.