Data Export API troubleshooting
Use this topic to interpret common Data Export API error responses and to identify
the most likely cause and fix for each one. Every error response includes a
code, a message, and a numeric statusCode; the code value identifies the specific condition.Authentication and authorization errors
| Error code | Likely cause | What to try |
|---|---|---|
ERR_INVALID_APIKEY (401) |
The x-api-key header is missing, malformed, expired, or has been deleted. Also occurs briefly (typically
less than one minute) immediately after a key is created or rotated, before the new
key is registered. |
Confirm that the request includes the x-api-key header with the full key value. In Account Administration, verify that the key still exists and has not expired. If the key was just created
or rotated, wait one minute and retry. |
ERR_UNAUTHORIZED_PRINTERS (403) |
The request includes one or more printerId values that the API key cannot access. |
Call /printers with the same API key to see exactly which printers are available, then submit the
request again with only those printer IDs. |
ERR_TENANT_NOT_FOUND (404) |
The API key is recognized but is not associated with an active account. This can happen if an account has been removed or is configured incorrectly. | Contact your Ricoh account representative to confirm that your tenant is active and that the API key is associated with it. |
Parameter validation errors (400 Bad Request)
Every parameter validation error returns a 400 status code. The code value identifies the specific problem.
| Error code | Likely cause | What to try |
|---|---|---|
ERR_MISSING_PRINTER_ID |
The request did not include any printerId values. At least one is required for /jobs and /printer-states. |
Add at least one printerId query parameter. Repeat the parameter to include multiple printers. |
ERR_INVALID_PRINTER_ID_FORMAT |
A printerId value is not a valid UUID. |
Verify the value against the response from /printers. Common mistakes include extra whitespace, missing characters, or pasting in the
printer name instead of the printer ID. |
ERR_INVALID_TIMEZONE |
The timezone value is missing or is not a valid IANA timezone identifier. |
Use a region-based identifier such as America/Denver or Europe/Bucharest. Three-letter abbreviations such as MST or EST are not accepted. The interactive documentation page lists every accepted value. |
ERR_INVALID_DATE_FORMAT |
A startDateTime or endDateTime value does not match the expected format. |
Use the format YYYY-MM-DDTHH:MM:SS, optionally with a .sss milliseconds suffix. Do not include a UTC offset or a Z suffix; the timezone is supplied separately in the timezone parameter. |
ERR_INVALID_DATE_RANGE |
startDateTime is the same as or later than endDateTime. |
Verify that startDateTime is earlier than endDateTime in the supplied timezone. |
ERR_DATE_RANGE_EXCEEDED |
The duration between startDateTime and endDateTime exceeds the maximum allowed range. |
Reduce the size of the requested time window. See Working with Data Export API response limits for chunking guidance. |
ERR_INVALID_JOB_STATE |
The jobState value is not one of the accepted values. |
Use one of printing, printed, aborted, or completed. Note that completed includes both printed and aborted jobs. |
ERR_INVALID_STATE_CATEGORY |
The stateCategory value is not one of the accepted values. |
Use one of up, down, or idle. |
ERR_INVALID_BOOLEAN_PARAM |
The currentState or stateCategoryOnly parameter has a value other than true or false. |
Use the literal lowercase strings true or false. |
ERR_UNKNOWN_PARAMETERS |
The request includes one or more parameters that the endpoint does not accept. | Compare the request against the parameters listed for the endpoint in the interactive documentation. Common causes include typos, parameters intended for a different endpoint, or extra tracking parameters added by an HTTP client. |
ERR_DUPLICATE_PARAMETERS |
The same parameter is supplied more than once and the endpoint does not accept duplicates for that parameter. | Verify the parameter list. The printerId parameter is allowed to repeat (once per printer); other parameters must appear at
most once. |
ERR_EMPTY_PARAMETERS |
A required parameter is present but has no value. | Verify that every required parameter has a non-empty value. |
ERR_INVALID_TENANT_ID |
The tenant identifier associated with the API key is invalid. | Contact your Ricoh account representative. |
Response size and method errors
| Error code | Likely cause | What to try |
|---|---|---|
ERR_RESPONSE_LIMIT_EXCEEDED (413) |
The data that matches the request would exceed the maximum response size. The response
body includes a maxJobs field that indicates the limit in effect. |
Narrow the date range, request fewer printers, or both, and submit the request again. See Working with Data Export API response limits for recommended chunking patterns. |
ERR_UNSUPPORTED_METHOD (405) |
The request used an HTTP method other than GET. |
The Data Export API supports only the GET method. Update your client to use GET. |
Server errors (500 Internal Server Error)
500 responses indicate an unexpected condition on the server. Retries are safe because
every Data Export API endpoint is a GET and produces no side effects. Wait a few seconds before retrying, and use exponential
backoff if the error persists.
| Error code | Likely cause | What to try |
|---|---|---|
ERR_INTERNAL_SERVER_ERROR |
An unexpected condition occurred on the server. | Wait a few seconds and retry. If the error persists for more than a few minutes, contact your Ricoh account representative. |
ERR_TENANT_CHECK_FAILED |
The server could not verify the tenant associated with the API key. | Wait a few seconds and retry. If the error persists, contact your Ricoh account representative. |
ERR_PRINTERS_FETCH_FAILED |
The server could not retrieve the list of printers for the tenant. | Wait a few seconds and retry. If the error persists, contact your Ricoh account representative. |
ERR_PRINTER_STATES_FETCH_FAILED |
The server could not retrieve printer state data for the request. | Wait a few seconds and retry. If the error persists, contact your Ricoh account representative. |
Other symptoms
- The response is empty (
[]) but you expect data - An empty array means no records matched the request. Verify the time window (the API
serves only the last seven days), the timezone, the
printerIdvalues, and any filters such asjobStateorstateCategory. - Date and time values in the response do not match what you expected
- Response timestamps are local times in the timezone supplied with the request. Submitting
the same request with a different
timezonevalue produces different timestamp strings even though they describe the same events. See Date and time handling in the Data Export API. - A printer is missing from the
/printersresponse - The API returns only printers that are monitored by a data collector. If a printer is missing, verify that it was registered to a data collector and is currently connected.
- A printer-states response includes
unknowncategories - An
unknowncategory indicates that the raw printer state could not be classified. See Printer states and state categories for the full state-to-category mapping.