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

For Business and Enterprise customers, there are no hard limits on the number of simultaneous API calls you can make. However, when resources are heavily utilized, you might encounter a throttle failure and receive a 503 Service Unavailable error. This doesn’t mean your conversion has failed permanently—it simply requires a retry after a brief pause.

Sample 503 Response

{
  "Code": 503,
  "Message": "The service is overloaded. Please retry in a couple of seconds."
}

Handling Throttle Errors

When you receive a 503 error, retrying the conversion at timed intervals is often all it takes to succeed. 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.