Error Handling

Always check errors

Every time you make an API call, an error may result. It’s essential to check these errors to ensure the smooth operation of your integration. This means checking return codes from API calls and/or catching exceptions thrown by underlying libraries, and handling them appropriately according to the type of error.

In general, errors fall into three broad categories:

• Client errors. For example, invalid API parameters. This type of error needs to be addressed on the client side. It could require modifying the client configuration or fixing a bug in the client code depending on the specific error. The HTTP status code for these errors is in the 4xx range.
• Server errors. The server was unable to service the request for some reason. This might be due to an unexpected error on the server side, or due to scheduled downtime. In general, it makes sense for the client to automatically retry the request after a delay. However, there are some situations in which the problem must be fixed on the client side, such as invalid regular expressions in directives. The HTTP status code for these errors is in the 5xx range.
• Network errors. The HTTP request/response was not successfully transmitted over the network. This could be due to a temporary network issue (such as a DNS interruption) so it usually makes sense to automatically retry the request a number of times. Since the HTTP communication did not succeed, there’s no HTTP status code for this type of error.

How a particular error should be handled depends on the details of the error. For example, an ‘invalid locale code’ error indicates a mismatch between the client configuration and that of the Smartling account, and likely needs to be manually corrected. On the other hand a 429 rate limiting error can be handled automatically by retrying the request after a delay.

It can be helpful to determine whether a particular error is ultimately recoverable or not. For example, a network outage might prevent a request being made for now (even with retries), but once the network problem is resolved it should be possible to resend that request successfully. In contrast, an attempt to delete something that no longer exists probably should not be attempted again, and thus could be considered unrecoverable.

Regardless of the type of error, your client code should write the details of the error to a log to facilitate later analysis. Many unrecoverable errors should also trigger an alert to ensure that someone investigates and resolves the issue.

Error response structure

Error responses from the API contain a body with the following JSON structure:

{
     "response": {
         "code": "ERROR_CODE",
         "errors": [
               {
                    "key": "error.keyv",
                    "message": "Error message",
                    "details": {
                          "field":"value"
                    }
               } 
        ]
     }
}

The response contains a code node and an errors node.

The errors node contains at least one error object which should contain enough information to identify the reason for the error. In some cases, the error object’s details node will be empty and set to null. At a minimum, there will be a key node which might be needed if working with Smartling support to investigate the error.

For details on possible code values, see Error Codes.

Logging

In order to assess unexpected errors or behaviour it’s crucial to have reliable logs available for analysing what happened. Most languages have ready-made libraries to facilitate logging with support for different logging levels, log rotation, etc., and many companies have logging systems available, such as Splunk, New Relic and DataDog.

What to log

Generally speaking, the more information you log the better, assuming suitable logging levels are used. At a minimum, the following information should be logged whenever an API error occurs:

• Error type and code. HTTP status code as well as Smartling error code and error key if available; or the type of network error, such as a timeout.
• Error details. Any additional details associated with the error. These can be found in the HTTP response, or in the exception.
• Request details. Details of the request sent that resulted in this error response: URL, api parameters, and any additional context. Additional, non-error logging can be helpful here too in order to clarify what was happening in the application before the error occurred.
• Request Tracking ID. Smartling includes a request tracking number in a response header in the format X-SL-RequestId: 369f4a6e-6f7f-4206-8a20-5485742a1d48. Make sure to log this ID as it can help Smartling find the request in its logs should you need to work with Smartling Support.

In addition, it’s recommended to log metrics reflecting ongoing activity of your service. For example, your integration might record a running count of files uploaded to Smartling; a sudden spike in this number might be cause for investigation.

Finally, it’s also useful to record environmental information on the service itself, such as how many instances of the service are running, CPU, memory and disk usage.

Good logging will ease problem diagnosis during development as well as when your integration is in production. When deciding what information to include in the logs, keep in mind that log files may ultimately be analysed by people unfamiliar with your integration code. Make sure to use appropriate logging levels and ensure that any log rotation configuration doesn’t overwrite old logs too quickly.

Log monitoring

To get the most value from log files it’s essential that problems be analysed close to the time when they occurred. This is achieved by sending alerts when problems arise. Many logging systems include log monitoring and alerting functionality. If this is not available, then it can be built into your integration. Logs should also be reviewed manually.

Retries

Retrying requests is usually appropriate in the following situations:

• Rate limiting. When a 429 HTTP status code is received, the client should retry the request after a delay. For more information, see Rate Limits.
• Network errors. These can be transient or permanent. It usually makes sense to retry a small number of times.
• Temporary server errors. For example, if the system is unavailable due to maintenance. The request should be retried after the maintenance window has passed. This example could be approached by simply letting the next scheduled run pick up and re-run the failed attempt, rather than using the coded retries approach appropriate for handling rate limits.

Make sure to choose appropriate retry parameters and to avoid retrying forever. If the retry process doesn't succeed then the issue may require human intervention.

Common causes of errors

Below are a few examples of common errors in API integrations. Each of these examples is due to either a bug or a misconfiguration of the API client application.

Invalid locale code

Each project in Smartling is configured with a set of target locales, which are defined by locale ID. A number of API endpoints take locale ID as a parameter, and these endpoints return an error if the locale ID does not match one that’s defined in the Smartling project. (Note: to see which languages are defined in a project, go to Project Settings > Languages in the Smartling Dashboard, or use the Get project details API call.)

Usually, this occurs because the source platform from which the content originates contains its own set of target languages and language IDs, and these don’t always match the Smartling ones.

In general, the recommended approach for managing languages in an integration with Smartling is to maintain a mapping between the language IDs in the source platform and those in Smartling. And ideally, this mapping should be exposed as part of the integration configuration.

Invalid file URI

Most integrations with Smartling involve the transfer of files, which are identified in a Smartling project by the file URI. Incorrect file URIs return an error, or in rare cases operate on the wrong file.

File URI problems are often traceable to how the file is named in the origin system, particularly when files are named by end users. These names can include unexpected characters such as emojis or linefeeds. Even when such names are valid on the Smartling side, they sometimes are lost when persisted by the integration code due to use of an incorrect encoding. If this happens subsequent API calls will use an invalid URI resulting in errors.

To avoid the above problems, it’s recommended to normalize file names used for Smartling URIs and maintain a mapping between the name of an item in the origin system and the corresponding URI in Smartling.

Invalid placeholder directive

Smartling supports custom placeholder formats by allowing you to specify a regular expression for recognizing placeholders when your content is parsed for translation. This regular expression is defined in a directive specified when uploading files for translation. If the expression is invalid, the file won’t be parsed or made available for translation. For some file uploads this error will be recognized at the point of upload. However, if files are uploaded via job batches, or if they take a long time to process, the error will not be returned at the point of upload.

To guard against the specific error due to invalid placeholder regular expressions, be sure to test these carefully. Putting directives into the file and manually dragging them into the Smartling dashboard is a convenient approach for testing. But also check that things are working via API, as regular expressions sometimes require different escaping depending on where they’re defined.

More generally, check the status of file uploads that returned a 202 instead of a 200 response; and check the status of job batches to ensure that they processed all of your files successfully.