Best practices for API error handling and troubleshooting

Orange APIs use common HTTP response status codes to indicate whether a specific HTTP request has been successfully completed or not. Only two classes of error codes are defined by HTTP/1.1 protocol:

• client errors (4xx)
• servers errors (5xx)

The list below provides the main HTTP status codes that can be returned by our Orange APIs, focusing on the 401, 403 and 503 codes:

Error response messages provide additional information about the underlying fault, that you can use to debug the error as well as providing user friendly feedback in your application. The error reporting is designed to make the APIs usable – easy to implement and debug.

The body of the response contains more details about the error. The body is JSON-formatted like regular responses. Errors are guaranteed to remain unchanged when using a specific API version.

Error response entities for errors have an HTTP status code (e.g. 401 Unauthorized) and up to four attributes – two mandatory and two optional as shown below:

• code – integer: An integer coding the error type
• message – string: A short localized string that describes the error
• description – string: (optional) A long localized error description if needed. It can contain precise information about which parameter is missing, or what are the acceptable values
• infoURL – URL: (optional) A URL to online documentation that provides more information about the error

For instance:

json
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
"code": 41,
"message": "Invalid credentials",
"description": "The requested service needs credentials, but the ones provided were invalid."
}

When requesting an OAuth access token using the POST /token operation, your application uses the ‘expire_in’ field that provides the period of validity for the access token, expressed in seconds (e.g. 7776000 -> 90 days, or 3600 -> 1 hour). Your application should cache this token and not request a new access token until receiving an error indicating that the access token has expired.

json
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"access_token": "i6m2iIcY0SodWSe...L3ojAXXrH",
"expires_in": "7776000"
}

Two types of quota could make your application rate-limited, depending on our Orange APIs configuration:

• Rate-limiting quota is set for all our APIs.
• Application quota is optional.

1. Rate-limiting quota
   To protect Orange APIs against abnormal peaks of traffic, we configured a maximum number of allowed requests per second, for all inbound traffic made by applications – i.e. max. 25 requests per second. When a new request comes in, the server determines if the rate limit is exceeded for the current window of time (i.e. second). If so, the request is rejected on error, until the quota counter resets.The following error message is returned to your application:

   json
   HTTP/1.1 403 Forbidden
   Content-Type: application/json
   
   {
   "code": 53,
   "message": "Too Many Requests",
   "description": "The application has made too many calls and has exceeded the spike arrest limit for this service."
   }

   When rate-limited, your application should wait a short delay (in the range of second) before retrying to send the request. Below an example in Java:

   java
   TimeUnit.SECONDS.sleep(1);
   OR Thread.sleep(1000);

2. Application quota. Let’s consider the two following examples:
   1. for a given API, we configured the maximum number of allowed requests per fixed window – i.e. max. 2500 requests per month. When a new request comes in, the server determines if the quota has been exceeded for your application during the time window. If so, the request is rejected on error, until the quota counter resets, at midnight GMT of the last day of the month.
   2. for another API, we configured the maximum number of allowed requests per rolling window – i.e. max. 600 requests per minute. When a new request comes in, the server determines if the quota has been exceeded for your application during the past time window. If so, the request is rejected on error. The counter never resets, but is recalculated on each request.In both cases, the following error message is returned to your application. Please note that , compared to rate-limiting quota, the error code and message are the same, but the description message changed (‘global quota limit’ instead of ‘spike arrest limit’).

   json
   HTTP/1.1 403 Forbidden
   Content-Type: application/json
   {
   "code": 53,
   "message": "Too Many Requests",
   "description": "The application has made too many calls and has exceeded the global quota limit for this service."
   }

   At client level, your application must process the response entity to extract the information about the error that occurred (i.e. HTTP status code, error code, error message, error description (optional)).

In practice, frameworks will help you. A good example is Spring MVC’s RestTemplate. By default, the RestTemplate throws an exception for any response in the 4xx or 5xx ranges. You can customize this by providing your own implementation of ResponseErrorHandler. The default error handling behavior often makes sense, as it prevents you from checking the status code after each request. You can let an exception interrupt the execution flow, as usual.

In distributed service/resource-oriented architecture, request IDs are a way of grouping all the information associated with a given request to a protected resource; the main benefits are two-fold:

• Provides a tagging mechanism for events that are produced, so that a full report of what occurred and timing in every component touched can be generated for troubleshooting purpose
• Exposes an identifier to developers, which can be used to track down specific issues that they’re running into. If a request is consistently failing and the developer has verified that the request is properly formulated, the request ID may be used to report a problem to the support team.

Every request made against Orange APIs returns a response header named `X-OAPI-Request-Id`. This header contains an opaque value that uniquely identifies the request.

_As an example_:

```json
HTTP/1.1 503 Internal Server Error
Date: Thu, 14 Sep 2017 06:49:12 GMT
Content-Type: application/json
Content-Length: 184
X-OAPI-Request-Id: opopecballrt02-31151-13125058-1

{
"code": 5,
"message": "The service is temporarily unavailable",
"description": "The service in charge of the requested endpoint is temporarily unavailable or unreachable."
}
```

If a request constantly fails and you have verified that the request is properly formulated, you may use this value to report the error to Orange as explained below.

1. Go to Contact us page
2. In the Request type drop-down list, select Technical, then I have a technical problem with an API used by my application
3. Select the API
4. Fill in the request details. Make sure to add:
   • information about the type of operation that the request attempted (e.g. POST https/api.orange/com/cloud/v1/folders -> create a new folder into Orange customer’s personal cloud),
   • the value of X-OAPI-Request-Id header
   • the approximate time that the request was made (e.g. Thu, 14 Sep 2024 06:49:12 GMT).