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.

Error response structures

We strive to keep our error responses consistent across all endpoints and provide additional information about the error where available. At the moment, there are three error response structures your application needs to handle:

Standard errors

Most errors return a JSON body with a detail field containing a message describing the error.

Example:

{
  "detail": "Language pair (en-GB -> en-US) is not supported"
}

Request validation errors

Request validation errors return detail as an array of objects, each pointing to the specific field that caused the issue.

Example:

{
  "detail": [
    {
      "loc": ["body", "target"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

note

These errors should be prevented ahead of time, as they generally describe an issue with the integration (e.g., invalid URL format, invalid language code format, etc.).

Asynchronous document translation errors

Some errors occur after a document has been accepted for translation. These are delivered via the error callback and/or the status polling endpoint, using a different structure with:

• reason: A human-readable error message
• errorCode: A machine-readable error code
• errorData: Additional metadata when available

Example:

{
  "reason": "Counted more words than allowed",
  "errorCode": "MAX_WORDS_EXCEEDED",
  "errorData": {
    "maxAllowedWords": 1000,
    "wordCount": 2000
  }
}

Best practices

For asynchronous errors, we recommend using the errorCode field if you want to customize error messages shown to users. The reason field can be used as a fallback message displayed to the user. However, we may change the wording of some messages, so do not build parsing logic around the reason field.

Future changes

Please note that we may add more error messages or codes in the future, so we advise implementing a generic fallback handler for unknown or unexpected errors.

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.
404	URL or resource not found	Check that your application sends the request to the correct URL.
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 accordingly.
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:

• Authentication
• Text management
• Document management
• Standards and formats
• Callbacks

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.