Dépannage de l'API d'exportation de données
Utilisez cette rubrique pour interpréter les réponses d'erreur courantes de l'API
d'exportation de données et pour identifier la cause la plus probable ainsi que la
solution à apporter pour chacune d'entre elles. Chaque réponse d'erreur comprend un
code, un message et un statusCode numérique ; la valeur code identifie la condition spécifique.Erreurs d'authentification et d'autorisation
| Code d'erreur | Cause probable | À découvrir |
|---|---|---|
ERR_INVALID_APIKEY (401) |
L'en-tête x-api-key est manquant, mal formé, périmé ou a été supprimé. Ce phénomène se produit également
brièvement (généralement moins d'une minute) immédiatement après la création ou la
rotation d'une clé, avant que la nouvelle clé ne soit enregistrée. |
Vérifiez que la requête comprend l'en-tête x-api-key avec la valeur complète de la clé API. Dans Account Administration, vérifiez que la clé existe toujours et qu'elle n'a pas expiré. Si la clé vient d'être
créée ou renouvelée, veuillez patienter une minute, puis réessayez. |
ERR_UNAUTHORIZED_PRINTERS (403) |
La requête contient une ou plusieurs valeurs printerId auxquelles la clé API n'a pas accès. |
Appelez la fonction /printers en utilisant la même clé API pour voir exactement quelles imprimantes sont disponibles,
puis renvoyez la requête en n'indiquant que les identifiants de ces imprimantes. |
ERR_TENANT_NOT_FOUND (404) |
La clé API est reconnue, mais elle n'est pas associée à un compte actif. Cela peut se produire si un compte a été supprimé ou s'il est mal configuré. | Veuillez contacter votre chargé de compte Ricoh afin de vérifier que votre tenant est actif et que la clé API y est bien associée. |
Erreurs de validation des paramètres (400 Erreur de requête)
Toute erreur de validation d'un paramètre renvoie un code d'état 400. La valeur du
code permet d'identifier le problème en question.
| Code d'erreur | Cause probable | À découvrir |
|---|---|---|
ERR_MISSING_PRINTER_ID |
La requête ne comportait aucune valeur printerId. Au moins un élément est requis pour /jobs, /printer-states et /printer-interventions. |
Veuillez ajouter au moins un paramètre de requête printerId. Répétez ce paramètre pour inclure plusieurs imprimantes. |
ERR_INVALID_PRINTER_ID_FORMAT |
La valeur printerId n'est pas un UUID valide. |
Vérifiez cette valeur par rapport à la réponse renvoyée par l'API /printers. Parmi les erreurs courantes, on peut citer les espaces superflus, les caractères
manquants ou le fait de coller le nom de l'imprimante à la place de son identifiant. |
ERR_INVALID_TIMEZONE |
La valeur timezone est manquante ou ne correspond pas à un identifiant de fuseau horaire IANA valide. |
Utilisez un identifiant basé sur une région, tel que America/Denver ou Europe/Bucharest. Les abréviations de trois lettres, telles que MST ou EST, ne sont pas acceptées. La page de documentation interactive présente la liste de
toutes les valeurs autorisées. |
ERR_INVALID_DATE_FORMAT |
Une valeur startDateTime ou endDateTime n’est pas appariée au format attendu. |
Utilisez le format YYYY-MM-DDTHH:MM:SS, éventuellement suivi d'un suffixe .sss pour les millisecondes. N'indiquez pas de décalage UTC ni de suffixe Z; le fuseau horaire est spécifié séparément dans le paramètre timezone. |
ERR_INVALID_DATE_RANGE |
startDateTime est identique à endDateTime ou postérieure à celle-ci. |
Vérifiez que startDateTime est antérieur à endDateTime dans le fuseau horaire indiqué. |
ERR_DATE_RANGE_EXCEEDED |
La durée comprise entre startDateTime et endDateTime dépasse la plage maximale autorisée. |
Réduisez la durée de la plage horaire demandée. Pour obtenir des conseils sur le découpage en blocs, consultez Gestion des limites de réponse de l'API d'exportation de données. |
ERR_INVALID_JOB_STATE |
La valeur jobState ne figure pas parmi les valeurs autorisées. |
Utilisez l'une des expressions suivantes : printing, printed, aborted ou completed. Veuillez noter que la mention completed englobe à la fois les travaux printed et aborted. |
ERR_INVALID_STATE_CATEGORY |
La valeur stateCategory ne figure pas parmi les valeurs autorisées. |
Utilisez l'une des options suivantes : up, down ou idle. |
ERR_INVALID_LANGUAGE |
La valeur langue fournie à /printer-interventions ne figure pas parmi les valeurs acceptées. |
Veuillez choisir l'une des langues suivantes : en, de, ja, it, fr ou es. Cette erreur signifie que le code lui-même a été rejeté ; un code qui est accepté
mais pour lequel il n'existe aucune traduction d'une description particulière ne génère
pas d'erreur, car l'API renvoie alors cette description en anglais à la place. |
ERR_INVALID_BOOLEAN_PARAM |
Le paramètre currentState ou stateCategoryOnly a une valeur autre que true ou false. |
Utilisez les chaînes de caractères littérales true ou false en minuscules. |
ERR_UNKNOWN_PARAMETERS |
La requête contient un ou plusieurs paramètres que le point de terminaison n'accepte pas. | Comparez la requête avec la liste des paramètres pour le point de terminaison dans la documentation interactive. Parmi les causes courantes, on peut citer les fautes de frappe, les paramètres destinés à un autre point de terminaison ou les paramètres de suivi supplémentaires ajoutés par un client HTTP. |
ERR_DUPLICATE_PARAMETERS |
Le même paramètre est fourni plusieurs fois, or le point de terminaison n'accepte pas les doublons pour ce paramètre. | Vérifiez la liste des paramètres. Le paramètre printerId peut apparaître plusieurs fois (une fois par imprimante) ; les autres paramètres
ne doivent apparaître qu'une seule fois au maximum. |
ERR_EMPTY_PARAMETERS |
Un paramètre obligatoire est présent, mais ne comporte aucune valeur. | Vérifiez que chaque paramètre obligatoire possède une valeur non vide. |
ERR_INVALID_TENANT_ID |
L'identifiant de locataire associé à la clé API n'est pas valide. | Veuillez contacter votre chargé de compte Ricoh. |
Erreurs liées à la taille de la réponse et à la méthode
| Code d'erreur | Cause probable | À découvrir |
|---|---|---|
ERR_RESPONSE_LIMIT_EXCEEDED (413) |
Les données appariées à la requête dépasseraient la taille maximale de la réponse.
Le corps de la réponse comprend un champ maxJobs qui indique la limite en vigueur. |
Restreignez la plage de dates, demandez moins d'imprimantes, ou les deux, puis renvoyez votre demande. Consultez Gestion des limites de réponse de l'API d'exportation de données pour connaître les modèles de regroupement recommandés. |
ERR_UNSUPPORTED_METHOD (405) |
La requête a utilisé une méthode HTTP autre que GET. |
L'API d'exportation de données ne prend en charge que la méthode GET. Mettez à jour votre client pour qu'il utilise GET. |
Erreurs de serveur (500 Erreur interne du serveur)
500 réponses indiquent une condition imprévue sur le serveur. Les nouvelles tentatives
ne présentent aucun risque, car chaque point de terminaison de l'API d'exportation
de données est une requête GET et ne produit aucun effet secondaire. Veuillez patienter quelques secondes avant
de réessayer, et utilisez un délai d'attente exponentiel si l'erreur persiste.
| Code d'erreur | Cause probable | À découvrir |
|---|---|---|
ERR_INTERNAL_SERVER_ERROR |
Une condition imprévue s'est produite sur le serveur. | Veuillez patienter quelques secondes, puis réessayez. Si l'erreur persiste pendant plus de quelques minutes, veuillez contacter votre chargé de compte Ricoh. |
ERR_TENANT_CHECK_FAILED |
Le serveur n'a pas pu vérifier le locataire associé à la clé API. | Veuillez patienter quelques secondes, puis réessayez. Si l'erreur persiste, veuillez contacter votre chargé de compte Ricoh. |
ERR_PRINTERS_FETCH_FAILED |
Le serveur n'a pas pu récupérer la liste des imprimantes pour ce locataire. | Veuillez patienter quelques secondes, puis réessayez. Si l'erreur persiste, veuillez contacter votre chargé de compte Ricoh. |
ERR_PRINTER_STATES_FETCH_FAILED |
Le serveur n'a pas pu récupérer les données d'état de l'imprimante correspondant à cette requête. | Veuillez patienter quelques secondes, puis réessayez. Si l'erreur persiste, veuillez contacter votre chargé de compte Ricoh. |
Autres symptômes
- La réponse est vide (
[]) alors que vous vous attendiez à recevoir des données - Un tableau vide signifie qu'aucun enregistrement n'a été apparié à la requête. Vérifiez
la plage horaire (l'API ne fournit que les données des sept derniers jours), le fuseau
horaire, les valeurs
printerIdet tous les filtres tels quejobStateoustateCategory. - Les valeurs de date et d'heure figurant dans la réponse ne correspondent pas à ce à quoi vous vous attendiez
- Les horodatages des réponses correspondent à l'heure locale dans le fuseau horaire
indiqué dans la requête. Si vous envoyez la même requête en indiquant une valeur
timezonedifférente, vous obtenez des chaînes de caractères d'horodatage différentes, même si elles décrivent les mêmes événements. Voir Gestion de la date et de l'heure dans l'API d'exportation de données. - Il manque une imprimante dans la réponse
/printers - L'API ne renvoie que les imprimantes surveillées par un collecteur de données. Si une imprimante est manquante, vérifiez qu'elle a bien été enregistrée auprès d'un collecteur de données et qu'elle a actuellement une connexion.
- Une réponse relative à l'état de l'imprimante comprend des catégories
unknown - Une catégorie
unknownindique que l'état brut de l'imprimante n'a pas pu être classé. Veuillez consulter États de l'imprimante et catégories d'états pour consulter la correspondance complète entre les états et les catégories.