Sign up
Documentation menu

Throttle and Fallback

At times, you might experience a throttle failure or a conversion error caused by corrupted data in the source file. But there's no need to panic! By implementing proper error handling, you can ensure that failed conversions retry successfully. In this guide, we'll show you how to manage these issues and keep your integration flawless.

Throttle Failures

Each plan includes a fixed number of concurrent conversions (see pricing); Enterprise plans have no concurrency limit. A 503 Service Unavailable error can occur when you exceed your plan's concurrency, or momentarily when the specific converter you are calling is running at capacity - regardless of plan. This doesn't mean your conversion has failed permanently - it simply requires a retry after a brief pause.

Sample 503 Response

{
  "Code": 503,
  "Message": "No available conversion PODs. Please retry after a few seconds."
}

The response also carries a Retry-After header with the recommended number of seconds to wait before retrying.

Handling Throttle Errors

When you receive a 503 error, retrying the conversion at timed intervals is often all it takes to succeed. Honor the Retry-After header when present; otherwise we recommend implementing a retry mechanism, following this pattern:

  1. First retry: Wait 5 seconds before retrying.
  2. Second retry: If it fails again, wait 10 seconds and retry.
  3. Third retry: Wait 15 seconds and retry.

By the third attempt, most requests should go through successfully.

Here's an example of how the retry process might look:

POST https://v2.convertapi.com/convert/docx/to/pdf → Response 503 → Retry  
↓  
Wait 5 seconds → Retry POST  
↓  
Wait 10 seconds → Retry POST  
↓  
Wait 15 seconds → Retry POST → Response 200 OK

Conclusion

Proper error handling is essential for ensuring smooth integrations with API services, reducing the likelihood of failed conversions. ConvertAPI provides clear error messages for all failure scenarios, including detailed guidance on Response Codes in our documentation. Be sure to handle these like a pro, so your integration remains seamless even in rare cases of service throttling.