ConvertApi Logo
Sign up

Throttle and Fallback!

Kostas, Developer

In some rare cases, you might encounter a throttle failure or a failed conversion due to corrupted data in the source file. But don’t worry, you are not at a dead end. Proper error handling may help the failing conversion to succeed. In this article, we will explain how to handle such cases to make your integration flawless.

Throttle failure

We do not rate-limit your API calls for our Business and Enterprise customers - you can make as many requests simultaneously as you wish, which sometimes leads to peak resource utilization. That’s where a throttle failure might happen, and you may receive 503 service unavailable error. Nevertheless, it doesn’t mean that you cannot convert your file. It simply means that you should retry the conversion in a few seconds.

Request response (HTTP status code 503)
{
  "Code": 503,
  "Message": "The service is overloaded. Please retry in a couple of seconds."
}

When this happens, it is up to you how you want to handle it. However, our suggestion is to retry the conversion 3 times:

  • Attempt to convert a file after 5 seconds
  • Attempt to convert a file after 10 seconds
  • Attempt to convert a file after 15 seconds
HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf - Response 503 → Retry
↓
Wait 5 seconds
Retry HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf - Response 503 → Retry
↓
Wait 10 seconds
Retry HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf - Response 503 → Retry
↓
Wait 15 seconds
Retry HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf -  Response 200 (OK) → Done

Usually, that’s all it takes to make the request succeed.

Conversion failed - Fallback!

Some documents may be partially corrupted or damaged and the conversion might fail. In this case, you will receive a 500 Internal Server Error - Conversion failure response, with the detailed message saying: 5001 Conversion failed.

Request response (HTTP status code 500)
{
  "Code": 5001,
  "Message": "Conversion failed."
}

Nevertheless, you can still try to convert the file using an alternative converter, despite the first converter not being able to process and repair it. Take a look at the advanced properties on the conversion page (in this example we are refering to the DOCX to PDF conversion):

Alternative converter

For this conversion, you can choose from one of the following:

In this case, you might implement a logic that retries the conversion three times, each time using a different converter. First, you may try to convert your document using the default Word converter. If the conversion fails you might try again using the OpenOffice converter. Even if it fails this time, you can try to convert the document using a Printer converter.

HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf - Response 200 (OK) → Done
↓
Response 5001
Retry HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf/converter/openoffice - Response 200 (OK) → Done
↓
Response 5001
Retry HTTP POST Request
https://v2.convertapi.com/convert/docx/to/pdf/converter/printer - Response 200 (OK) → Done

In order to make your integration robust and reliable, we strongly recommend handling a 5001 Conversion failed error, and if that happens, retry the conversion using an alternative converter.

Conclusion

It is necessary to handle the errors properly when integrating an API service into your solution to minimize conversion failures. ConvertAPI provides detailed error messages for all possible failure scenarios. You can find the complete Response Codes overview in our documentation. Make sure to handle those like a pro!