Error Handling

Overview

The iiniit API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with the iiniit servers.

This guide will help you understand how to handle errors from the iiniit API and implement robust error handling in your applications.

Error Response Format

When an error occurs, the API returns a JSON response with details about the error. The response includes the following fields:

{
  "error": {
    "code": "string",
    "message": "string",
    "innererror": { 
      "code": "string"
    },
    "details": []
  }
}
    

Error Response Properties

• The code property contains a machine-readable value that you can take a dependency on in your code.

• The innererror object might recursively contain more innererror objects with more specific error codes properties. When handling an error, apps should loop through all the nested error codes that are available and use the most detailed one that they understand.

• The message property is a human-readable value that describes the error condition. Don't take any dependency on the content of this value in your code.

• The message property at the root contains an error message intended for the developer to read. Error messages aren't localized and shouldn't be displayed directly to the user. When handling errors, your code shouldn't take any dependency on the message property values because they can change at any time, and they often contain dynamic information specific to the failed request. You should only code against error codes returned in code properties.

• The details property is an optional array of error objects that have the same JSON format as the top-level error object. If a request is composed of multiple operations, such as a bulk or batch operation, it might be necessary to return an independent error for each operation. In this case, the details list is populated with these individual errors.

HTTP Status Codes

The iiniit API uses the following HTTP status codes: