Skip to content
English
  • There are no suggestions because the search field is empty.

Troubleshoot an API integration

Start with the failing operation, its HTTP response and the identity used by the application.

[Step] 1. Authentication stopped: check refresh-token rotation and the client ID

Check refresh-token rotation. Each refresh consumes the old token and returns a new one. Save the replacement in writable protected storage. Reusing the old token or storing it only in a fixed environment setting breaks renewal.

Reuse the same OAuth client ID across builds. Refresh tokens are bound to the client that issued them.

[/Step]

[Step] 2. Sign-in fails: check permissions, callbacks and the PKCE token exchange

  • Missing administrator role or accounts scope: reconnect MCP with the appropriate administrator account and consent.
  • Invalid callback: check exact spelling, HTTPS or localhost, and that the URI is registered. The MCP registration tool rejects wildcards, fragments and native schemes.
  • Client management unavailable: contact ezeep through the API contact form.
  • Client limit reached: reuse an existing client or use the management API to remove an unused one.

For public PKCE clients, include the original code verifier at token exchange and use the client-ID-plus-colon Basic header. Do not use the MCP server’s own authorization endpoint inside your application.

[/Step]

[Step] 3. Endpoint rejected: check its host, path, trailing slash and HTTP method

Check the host and path family, exact endpoint spelling and trailing slash. PrepareUpload is a GET request; send the filename as a query parameter rather than posting JSON to that endpoint.

[/Step]

[Step] 4. HTTP 412: resend Print with the returned fileid; do not upload again

The print data is already stored. Use the fileid from the response body to resend the Print request. Do not download or upload the document again.

[/Step]

[Step] 5. HTTP 428: make the file URL downloadable without interactive sign-in

ezeep could not retrieve the file. Check that the URL downloads the actual document and includes the access information needed. This response does not contain a fileid.

[/Step]

[Step] 6. Request timed out: check the job before submitting another print

Do not automatically submit the print again. Check whether a job was already created using the available job ID and portal records. Another successful submission can print a duplicate.

[/Step]

[Step] 7. Job accepted but no page: check job, Connector and printer status

Check the job status and connector status. A printer behind an offline connector can accept a queued job and wait for the connector to return.

Check the printer’s own status and the selected print settings. For a Hub-connected printer, use the Hub troubleshooting guide.

[/Step]

[Step] 8. Job ID rejected: use the exact jobid from Print and URL-encode it

Use the exact jobid returned by Print and URL-encode it. A file ID or printer ID is not a job ID.

The Printing Quick Guide contains the response details and error-code reference.

[/Step]