Error handling
Response codes
LanguageWire MT API uses conventional HTTP response codes, as defined in the RFC 2616 and RFC 6585 to indicate the category of the failure of a request.
In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate an error that a request failed given the information provided (e.g., a required parameter missing, invalid authentication, etc.).
- Codes in the 5xx range indicate an error coming from LanguageWire servers.
Info
For more details about response codes and times check the standards and formats guide.
Frequent error codes
These are some of the most common general error codes you might get while using MT API endpoints, along with additional information about how to solve them.
| HTTP Status Code | Error description | Solution |
|---|---|---|
| 401 | Missing or invalid authentication credentials | You must be authorised by the system via an access token. Before starting your integration, generate your access credentials and try again. Alternatively, the access token provided is expired, malformed, or invalid for other reasons. You can try to generate a new access token and retry the request. 📧 Contact us in case of doubt. |
| 403 | The request requires higher privileges than provided by the access token. | Check that your client ID has the right permissions set to it. |
| 422 | The request body is not valid. Either a required field is missing or an invalid JSON was provided. | Check the details field included in the endpoint response to see more information about the error and amend accordantly. |
| 429 | You send too many requests in a time interval (Rate limit has been applied). | - If the error occurs while developing your integration: Wait a few minutes and try again with a good delay (30 seconds). If the error persists, contact us. - If the error occurs while running your integration in production: We recommend you to set a retry strategy*. |
| 500 | There is a temporary error in our server. | - If the error occurs while developing your integration: Wait a few minutes and try again with a good delay (30 seconds). If the error persists, contact us. - If the error error occurs while running your integration in production: We recommend you to set a retry strategy*. |
| 503/504 | The server is unavailable or it took too long to process the request. | - If the error occurs while developing your integration: Wait a few minutes and try again with a good delay (30 seconds). If the error persists, contact us. - If the error occurs while running your integration in production: We recommend you to set a retry strategy*. |
Tip*
- Limit the number of concurrent requests that your system creates within the rate limit time window.
- Set a retry strategy with exponential back-off for requests that return 429 or 5xx status codes.
- Check our rate limit guidelines for more details about timeouts and throttling policy.
Translate text
When sending text for translation via the POST /v2/translate endpoint, you might see some of the errors listed below.
| HTTP Status Code | Error description | Solution |
|---|---|---|
| 422 | The selected language pair is not supported. | Before sending a translation: 1. Query the GET /v2/languages/text-translation endpoint to see the full list of supported pairs. 2. Then, submit the request again with a valid language pair. Pay attention to language restrictions and codes. If the error happened after the /v2/languages/text-translation is queried, you can use an exponential retry. |
| 422 | The text content exceeds the limits (text too long, too many segments, etc.). | - Split the text in sentences so that the length limitation for a single segment is not reached. - Submit in batches of up to 100 segments*, where ideally 1 segment contains a single sentence. - Check the text size and segment restrictions and adjust if needed. |
Tip
- Use batch requests when possible, so instead of submitting a translation request per each of the segments, send 1 request with up to 100 segments (or sentences) for a given language pair which will reduce massively the number of calls.
- If the maximum content limit for batch is reached, split the segments across multiple batches.
Translate document
These errors and suggestions are specific for the POST /v2/documents/translate endpoint.
| HTTP Status Code | Error description | Solution |
|---|---|---|
| 422 | - The selected language pair is not supported. - Document is too large - Invalid file name - Unsupported document type or format | - Query the GET /v2/languages/document-translation endpoint to see the full list of supported pairs.- Check the size recommendations and adjust if needed. - Check the file name recommendations and adjust if needed. - Run the GET /v2/documents/types endpoint to see the compatible formats. Then, amend or convert your document and try again. |
Download translated document
These errors and suggestions are specific for the GET /v2/documents/:jobId/download endpoint.
| HTTP Status Code | Error description | Solution |
|---|---|---|
| 404 | Document translation not found. Either the ID never existed, or the document job was deleted because it was more than 1 hour ago. | If possible, download the document immediately after receiving the "success callback". |
| 422 | Translated document is not available. Either the translation has not yet finished or it failed. | Only attempt to download the translated document after the "success callback" has been sent or if the status field is set to SUCCESS in the GET /v2/documents/:jobId endpoint. |
More information
For more information, see reference guidelines:
Something missing? If you are experiencing any other error that is not listed in this page, share it with us so we can investigate and take further actions.