Risoluzione dei problemi relativi all'API di esportazione dei dati
Utilizzare questa sezione per interpretare le risposte di errore più comuni dell'API
di esportazione dei dati e per individuare la causa più probabile e la soluzione per
ciascuna di esse. Ogni risposta di errore include un
code, un message e un statusCode numerico; il valore del code identifica la condizione specifica.Errori di autenticazione e autorizzazione
| Codice di errore | Probabile causa | Cosa provare |
|---|---|---|
ERR_INVALID_APIKEY (401) |
L'intestazione x-api-key è assente, non conforme, scaduta o è stata eliminata. Si verifica inoltre per un
breve periodo (in genere meno di un minuto) immediatamente dopo la creazione o la
rotazione di una chiave, prima che la nuova chiave venga registrata. |
Si assicuri che la richiesta includa l'intestazione x-api-key con il valore completo della chiave API. In Account Administration, verifichi che la chiave esista ancora e non sia scaduta. Se la chiave è stata appena
creata o aggiornata, attenda un minuto e riprovi. |
ERR_UNAUTHORIZED_PRINTERS (403) |
La richiesta include uno o più valori di printerId a cui la chiave API non può accedere. |
Chiamare /printers utilizzando la stessa chiave API per verificare esattamente quali stampanti sono
disponibili, quindi inviare nuovamente la richiesta indicando solo gli ID di tali
stampanti. |
ERR_TENANT_NOT_FOUND (404) |
La chiave API viene riconosciuta, ma non è associata a un account attivo. Ciò può verificarsi qualora un account sia stato sottoposto a rimozione o sia configurato in modo errato. | Contattare il proprio referente commerciale Ricoh per verificare che il proprio tenant sia attivo e che la chiave API sia associata a esso. |
Errori di convalida dei parametri (400 Richiesta non valida)
Ogni errore di convalida dei parametri restituisce un codice di stato 400. Il valore
del code identifica il problema specifico.
| Codice di errore | Probabile causa | Cosa provare |
|---|---|---|
ERR_MISSING_PRINTER_ID |
La richiesta non includeva alcun valore di printerId. È richiesto almeno uno per i /jobs, /printer-states e /printer-interventions. |
Aggiunga almeno un parametro di query printerId. Ripetete il parametro per includere più stampanti. |
ERR_INVALID_PRINTER_ID_FORMAT |
Il valore printerId non è un UUID valido. |
Verifichi il valore confrontandolo con la risposta ottenuta da /printers. Tra gli errori più comuni figurano spazi superflui, caratteri mancanti o l’inserimento
del nome della stampante anziché del suo ID. |
ERR_INVALID_TIMEZONE |
Il valore di timezone è mancante oppure non costituisce un identificatore di fuso orario IANA valido. |
Utilizzi un identificatore basato sull'area, ad esempio America/Denver o Europe/Bucharest. Non sono ammesse abbreviazioni di tre lettere, quali MST o EST. La pagina della documentazione interattiva presenta un elenco di tutti i valori
ammessi. |
ERR_INVALID_DATE_FORMAT |
Il valore di startDateTime o endDateTime non è corrispondente al formato previsto. |
Si utilizzi il formato YYYY-MM-DDTHH:MM:SS, eventualmente con il suffisso .sss che indica i millisecondi. Non includa un offset UTC né un suffisso Z; il fuso orario viene specificato separatamente nel parametro timezone. |
ERR_INVALID_DATE_RANGE |
startDateTime è uguale o posteriore a endDateTime. |
Si verifichi che startDateTime sia anteriore a endDateTime nel fuso orario specificato. |
ERR_DATE_RANGE_EXCEEDED |
L'intervallo di tempo compreso tra startDateTime e endDateTime supera l'intervallo massimo consentito. |
Riduca l’ampiezza dell’intervallo di tempo richiesto. Per indicazioni sulla suddivisione in blocchi, si prega di consultare il sito Gestione dei limiti delle risposte dell'API di esportazione dei dati. |
ERR_INVALID_JOB_STATE |
Il valore di jobState non rientra tra i valori ammessi. |
Utilizzi uno dei seguenti termini: in fase di printing, printed, aborted o completed. Si noti che la voce completed comprende sia i lavori printed che quelli aborted. |
ERR_INVALID_STATE_CATEGORY |
Il valore di stateCategory non rientra tra i valori consentiti. |
Utilizzi una delle seguenti opzioni: up, down o idle. |
ERR_INVALID_LANGUAGE |
Il valore della language fornito a /printer-interventions non rientra tra i valori ammessi. |
Si prega di utilizzare una delle seguenti lingue: en, de, ja, it, fr o es. Questo errore indica che il codice stesso è stato rifiutato; un codice che viene
accettato ma per il quale non è disponibile una traduzione di una determinata descrizione
non genera un errore, poiché l'API restituisce invece quella descrizione in inglese. |
ERR_INVALID_BOOLEAN_PARAM |
Il parametro currentState o stateCategoryOnly ha un valore diverso da true o false. |
Si utilizzino le stringhe letterali in minuscolo true o false. |
ERR_UNKNOWN_PARAMETERS |
La richiesta contiene uno o più parametri che l'endpoint non accetta. | Confronti la richiesta con l'elenco dei parametri per l'endpoint nella documentazione interattiva. Tra le cause più comuni figurano errori di battitura, parametri destinati a un endpoint diverso o parametri di tracciamento aggiuntivi inseriti da un client HTTP. |
ERR_DUPLICATE_PARAMETERS |
Lo stesso parametro viene fornito più di una volta e l'endpoint non accetta duplicati per quel parametro. | Verifichi l'elenco dei parametri. Il parametro printerId può essere ripetuto (una volta per ogni stampante); gli altri parametri devono comparire
al massimo una volta. |
ERR_EMPTY_PARAMETERS |
È presente un parametro obbligatorio, ma privo di valore. | Si assicuri che ogni parametro obbligatorio abbia un valore non vuoto. |
ERR_INVALID_TENANT_ID |
L'identificativo del tenant associato alla chiave API non è valido. | Si prega di contattare il proprio referente commerciale Ricoh. |
Errori relativi alle dimensioni della risposta e al metodo
| Codice di errore | Probabile causa | Cosa provare |
|---|---|---|
ERR_RESPONSE_LIMIT_EXCEEDED (413) |
I dati corrispondenti alla richiesta supererebbero la dimensione massima della risposta.
Il corpo della risposta include un campo maxJobs che indica il limite in vigore. |
Restringa l'intervallo di date, richieda un numero inferiore di stampanti, oppure faccia entrambe le cose, e invii nuovamente la richiesta. Si veda Gestione dei limiti delle risposte dell'API di esportazione dei dati per i modelli di suddivisione consigliati. |
ERR_UNSUPPORTED_METHOD (405) |
La richiesta ha utilizzato un metodo HTTP diverso da GET. |
L'API di esportazione dei dati supporta esclusivamente il metodo GET. Aggiorni il Suo client in modo che utilizzi il metodo GET. |
Errori del server (500 Errore interno del server)
Il codice di risposta 500 indica una condizione imprevista sul server. I tentativi
ripetuti sono sicuri poiché ogni endpoint dell'API di esportazione dei dati è di tipo
GET e non produce effetti collaterali. Attenda alcuni secondi prima di riprovare e, qualora
l'errore dovesse persistere, ricorra al backoff esponenziale.
| Codice di errore | Probabile causa | Cosa provare |
|---|---|---|
ERR_INTERNAL_SERVER_ERROR |
Si è verificata una condizione imprevista sul server. | Attenda qualche secondo e riprovi. Se l'errore persiste per più di qualche minuto, si prega di contattare il proprio referente commerciale Ricoh. |
ERR_TENANT_CHECK_FAILED |
Il server non è riuscito a verificare il tenant associato alla chiave API. | Attenda qualche secondo e riprovi. Se l'errore persiste, si prega di contattare il proprio referente commerciale Ricoh. |
ERR_PRINTERS_FETCH_FAILED |
Il server non è riuscito a recuperare l'elenco delle stampanti relative al tenant. | Attenda qualche secondo e riprovi. Se l'errore persiste, si prega di contattare il proprio referente commerciale Ricoh. |
ERR_PRINTER_STATES_FETCH_FAILED |
Il server non è riuscito a recuperare i dati relativi allo stato della stampante per la richiesta in questione. | Attenda qualche secondo e riprovi. Se l'errore persiste, si prega di contattare il proprio referente commerciale Ricoh. |
Altri sintomi
- La risposta è vuota (
[]) ma Lei si aspetta dei dati - Un array vuoto indica che nessun record corrispondeva alla richiesta. Verifichi l'intervallo
di tempo (l'API fornisce dati solo relativi agli ultimi sette giorni), il fuso orario,
i valori di
printerIded eventuali filtri qualijobStateostateCategory. - I valori relativi alla data e all'ora presenti nella risposta non corrispondono a quanto da Lei previsto
- Le date/ore delle risposte corrispondono all'ora locale nel fuso orario specificato
nella richiesta. L'invio della stessa richiesta con un valore di
timezonediverso genera stringhe di data/ora diverse, sebbene descrivano gli stessi eventi. Consultare Date e ora: gestione nell'API di esportazione dei dati. - Nella risposta
/printersmanca una stampante - L'API restituisce solo le stampanti monitorate dalla raccolta dati. Se manca una stampante, verifichi che sia stata registrata su un dispositivo di raccolta dati e che abbia attualmente una connessione.
- Una risposta relativa allo stato delle stampanti include categorie
unknown - Una categoria
unknownindica che non è stato possibile classificare lo stato grezzo della stampante. Si prega di consultare il sito Stati della stampante e categorie di stato per la mappatura completa tra stato e categoria.