Integration best practices

We recommend you follow these best practices to ensure the best possible integration.

For maximum compatibility and durability of your integration application, we recommended you follow the best practices listed on this page. Not all of the notes apply to every integration. For example, parsing json is not relevant for applications requesting API responses in xml format. However, it is a good practice to keep the points below in mind.

Backwards compatibility

Infobip API evolves over time. We work hard to add new functionalities and improve existing ones with new features. In doing so, we will maintain backward compatibility according to a couple of rules. Abiding by those rules will ensure that your integration continues to work properly with any future API improvements while allowing you to easily take advantage of those new features.

Adding new fields to existing resources

One of the ways that we will use to introduce new features to the existing API endpoints is through adding new properties to existing request and/or response models. For example:

Original response model:
    "status": "OK",
    "statusId": 1

Extended response model:
    "status": "OK",
    "statusId": 1,
    "statusDescription": "All went well, no additional actions required"

When adding properties to request models we will always ensure that the field is optional so that all of the existing integrations continue to work without problems.

Regarding the properties in response models, however, you should ensure that your parsing implementation does not break when it encounters unspecified properties. That way you will not have to update your code every time a new feature is added to the API. At the same time, if you choose to use the new feature, updating your code will be simplified since you will only need to parse one new property.

JSON property order

Json specification does not guarantee the order of name/value pairs in objects, so your json parsing implementation should not depend on it either. In practice this means that the following json objects are considered to be identical:

Example object:
    "status": "OK",
    "statusId": 1

Equivalent object:
    "statusId": 1,
    "status": "OK"

API implementation may interchangeably return any of the above example objects and they should be treated identically by the client code. Fortunately, if json parsing is delegated to your language’s native functionality or one of the established parsing libraries this should already be handled properly by those implementations.

Date formats

API will generally return dates in a predefined and uniform format. Consult the dedicated documentation page for details on a specific endpoint. The format used by default is:


Note that the format encodes, and requires a time zone information. This means that the two seemingly different date time strings actually represent the same point in time:


When parsing dates received from the API you should take the time zone into account. It is best practice to convert the string received from the API into your language’s native representation of the moment in time. Then it can be processed and the time zone and format of your choosing will be displayed to your users. It is important to note not to expect that date times returned from the API will always be in a predefined time zone. Instead, you should use the returned time zone information.

Preventing errors

Besides ensuring that your application will continue to be compatible with the future developments on the API it is also important to keep it free of bugs. To help you with that here are a couple of common problems that should be taken into account.

Request body content types

As discussed in the dedicated documentation page, every request that contains message body data should contain a Content-Type header. Supported content types are application/json and application/xml. In each case, the body data that you send in your request should match the supplied Content-Type header and be valid.

json content

If you choose to use json make sure that you serialize your data into valid json objects. Specifically, watch out for string values. They should not contain double quote characters (") as including them would mark an end of a string. If double quotes are needed make sure they are escaped with a backslash (\). Furthermore, make sure that name/value pairs in your json objects are separated by commas (,). If you opt to use some of the standard serialization libraries this should all be implemented already.

  "stringProperty": "properly \"quoted\" string value",
  "numberProperty": 47,
  "booleanProperty": true,
  "nullProperty": null
  "stringProperty": "properly "quoted" string value"
  "numberProperty": 47
  "booleanProperty": true
  nullProperty: null
xml content

If you are using xml, also make sure that your objects are properly serialized into valid xml. Specifically, check that you are closing all of your tags and that you are doing so in the correct order. Also, note that the tags are case sensitive. Again, a well-established xml serialization library or native language function should take care of all of this.

    <nestedProperty>Some Value</nestedProperty>
    <nestedProperty>Some Value</outerProperty>

Deprecated standards

With the passing of time industry standards can become deprecated. The prime example of this is the usage of the SHA-1 hashing function in SSL certificates. As noted in the security and authorization documentation section, it is strongly recommended to connect to our API using the HTTPS protocol. Since SHA-1 has been deprecated and support for it is being removed from modern technology stacks and applications, our API is signed by certificates created using newer algorithms. In order to recognize it, your stack should use them as well.

Handling errors

Even in a normal integration operation, it is expected to encounter some error responses from the API. In cases when an error occurs we will attempt to fill the API response with a recognizable and self-explanatory message. In those cases, it is advisable to have your code analyze the API response and react to them in an appropriate manner.

HTTP response codes

You can find the list of all HTTP response codes with their meaning explained here. We will strive to return the appropriate status code to every request. Examining the returned status code is the first thing you can do to determine how to react to an API response.

Generally, any status in the 200s range ( from 200 up to 299 ) is considered to be successful and no additional reaction is needed.

Responses with a status code in the 400s range ( 400 to 499 ) indicate that there was something wrong with your request. Immediately sending the exact same request again will result in the same error so it is not advisable. Instead, you can analyze the specific status returned and adapt accordingly. If for example, the status 400 (Bad request) is returned, you should double check your Content-type header, check that your request body data is properly serialized and that the data sent to the API corresponds to the specified request model from the dedicated API endpoint documentation page. On the other hand, receiving the status 404 (Not found) means that either the requested API endpoint or the exact resource do not exist. In this case, double check the API endpoint path defined in the dedicated documentation page.

Status codes in the 500s range ( 500 to 599 ) signal that the request is valid but an error occurred on the API side. Depending on the specific status the error might be temporary so retrying the same request may yield different results.


One of the specific errors that can occur with your requests is a throttling error. It will generally be denoted by an HTTP status code 429 (Too Many Requests) and it happens when you make too many requests to a specific endpoint within a predefined amount of time.

Infobip API does not have a single throttling rule for all endpoints. Instead, some of them might have dedicated rules. To find specific ones revert to the dedicated documentation pages. For example, you can make as many send SMS requests as you wish. Those endpoints are considered to be used for traffic and have no limitations. On the other hand, fetching sent SMS logs is an administrative endpoint that should be used for bulk reporting. Because of that, there is a limit on the number of requests allowed in a time window. Any subsequent get logs requests will receive status code 429 and will not be carried out until enough time passes.

In case one of your API requests ends up being throttled, you could hold on for a little while and then retry it again. However, be mindful of retrying too many times, since you could cause even more requests to be throttled. When implementing retry logic make sure to include a limit on the number of retries and monitor the overall number of throttled requests. If too many of your requests end up being throttled you might be using the API in an unsupported way.