Troubleshooting

Common issues and how to resolve them.

API returns 401 Unauthorized

Your API key is missing or invalid.

Ensure you are passing the key in the x-api-key header or as a Bearer token
Check that the key has not been revoked — visit Settings → Developers

API returns 403 Forbidden

Your account does not have permission for this action.

You may have exceeded your daily conversion quota (Free plan: 1 GB / day, or 25 conversions)
Your account might be suspended. Contact support
Some features require a Pro or Business plan

API returns 429 Too Many Requests

You have exceeded your rate limit or active queue quota.

Wait for the rate limit window to reset (check X-RateLimit-Reset)
If jobs are queued, wait for current processing jobs to finish before submitting new tasks
Implement exponential backoff in your client application
Upgrade your plan for higher limits

Conversion fails or returns 400 Bad Request

Same-format conversion: Converting a file to its own format (e.g. PDF → PDF) returns SAME_FORMAT. To reduce size, use our optimization endpoints or pass compression options.
Unsupported format: Formats requiring external desktop engines (such as MOBI/AZW3 requiring Calibre or DWG/STEP requiring CAD kernels) are rejected with a clear descriptive message.
Inapplicable option: Sending an option that does not apply to the target format's category (e.g., sending bitrate for a document) returns OPTION_NOT_APPLICABLE.
File encrypted: Password-protected or DRM-encrypted files cannot be processed.

Status Tracking & Webhooks

Two ways to learn that a conversion finished:

Poll GET /api/conversions/:id every 2–5 seconds until status is completed or failed
Once complete, fetch the generated file using the provided outputUrl

Or subscribe to webhooks and let OrbConvert call you: see the webhook documentation for the events and payload, and the Developers tabin settings to add an endpoint. "Send test event" there proves your receiver works without running a conversion.

Getting Help

Was this page helpful?

API returns 429 Too Many Requests

You have exceeded your rate limit or active queue quota.

Wait for the rate limit window to reset (check X-RateLimit-Reset)
If jobs are queued, wait for current processing jobs to finish before submitting new tasks
Implement exponential backoff in your client application
Upgrade your plan for higher limits

Conversion fails or returns 400 Bad Request

Same-format conversion: Converting a file to its own format (e.g. PDF → PDF) returns SAME_FORMAT. To reduce size, use our optimization endpoints or pass compression options.
Unsupported format: Formats requiring external desktop engines (such as MOBI/AZW3 requiring Calibre or DWG/STEP requiring CAD kernels) are rejected with a clear descriptive message.
Inapplicable option: Sending an option that does not apply to the target format's category (e.g., sending bitrate for a document) returns OPTION_NOT_APPLICABLE.
File encrypted: Password-protected or DRM-encrypted files cannot be processed.

Status Tracking & Webhooks

Two ways to learn that a conversion finished:

Poll GET /api/conversions/:id every 2–5 seconds until status is completed or failed
Once complete, fetch the generated file using the provided outputUrl