Troubleshoot agents, printers and print jobs
Start with the job status and request identifier, then check the printer, agent and source document. This order reduces the risk of duplicate printing and usually reveals where the problem occurred.
Collect the identifiers first
Record the external order or document number, CloudPrint print_job_id, printer_id, latest status, failure_reason and X-Request-Id. Do not create another job until you know whether the first request was accepted. If the original request can be retried, reuse the same Idempotency-Key.
The printer is missing or offline
Confirm that the local agent is running and connected to the same CloudPrint account. Check the printer in the operating system, then refresh the printer list. A renamed queue may keep the same CloudPrint identifier, so route by printer_id, not by the displayed name. If the agent is offline, fix its outbound network access before changing API code.
The API rejects the job
A 401 usually means an invalid or expired token; request a new token once. A 403 means the token lacks a required scope. A 409 can indicate an idempotency conflict or an unsupported route. A 422 means the payload or print options are invalid. A 415 means the uploaded format is not supported.
The job is pending for too long
Check that the assigned agent is online, then inspect printer status_evidence, including reasons and accepting_jobs. Pending work cannot reach a disconnected location or a queue that is not accepting jobs. Keep polling with a bounded interval and never submit automatic copies.
The job failed after delivery
Read failure_reason and compare the document format and requested options with the printer capabilities. Typical causes include a missing PDF renderer, a RAW language the printer did not advertise, or unavailable system printing. For labels, also verify DPI, media dimensions, driver, queue and calibration.
Escalating to support
Provide X-Request-Id, print_job_id, approximate time, account, agent and printer names, document format, requested options and the visible failure reason. Do not send client secrets, access tokens or confidential document contents in a support message.