Troubleshoot an API integration
Start with the failing operation, its HTTP response and the identity used by the application.
On this page
- Authentication stopped: check refresh-token rotation and the client ID
- Sign-in fails: check permissions, callbacks and the PKCE token exchange
- Endpoint rejected: check its host, path, trailing slash and HTTP method
- HTTP 412: resend Print with the returned fileid; do not upload again
- HTTP 428: make the file URL downloadable without interactive sign-in
- Request timed out: check the job before submitting another print
- Job accepted but no page: check job, Connector and printer status
- Job ID rejected: use the exact jobid from Print and URL-encode it
[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]