Handling errors
Staying ahead of issues and known error conditions is important to all integration projects. Your integration should plan ahead and decide how to handle the following known error conditions that the Controlant Integration API can return for a request.
Error responses and how to handle them
We highly recommend planning ahead and deciding how to handle the following known error conditions that the Controlant Integration API can return for a request.
Handling known API errors
Each request to the API returns a predefined standard HTTP status. This status indicates whether the request was processed successfully, and if not, what type of error occurred.
The HTTP status can take one of the following values:
Status | Response | Description |
---|---|---|
200 | Successful | No errors. |
400 | Validation error | Input data does not conform to the API specifications for this function. Please see the response for details on the error. Retrying with the same arguments will not work. |
401 | Authentication error | The API Key could not be validated. |
500 | Server-side error | Server side error, unexpected condition was encountered. Sometimes this is the result of a coding or configuration error made by Controlant. |
504 | Internal communication server-side error | Temporary internal connectivity issue. It is safe to retry the action in a few minutes. |
Example HTTP error response
< HTTP/1.1 401 Unauthorized < Date: Mon, 17 Feb 2024 13:00:12 GMT < Server: Kestrel < Content-Length: 0 < WWW-Authenticate: APIKey error=No APIKey authentication header value found < x-correlation-id: 982411d3-1d9a-432b-8b98-fcb611c44fae
Note
All responses return a CorrelationId
that should be logged by the caller and used when referring to the issue with Controlant.
For more information about CorrelationId
, see Tracking requests using correlation Identifiers.
Validation errors (HTTP Status 400)
curl -X POST \ -H "Authorization: APIKey MYAPIKEY" \ -H "Content-Type: application/json" \ -H "x-api-version: 1" \ https://integrations.uat.controlant.com/api/echo < HTTP/1.1 400 Bad Request < Date: Tue, 18 Feb 2024 12:52:17 GMT < Content-Type: application/json; charset=utf-8 < Server: Kestrel < Content-Length: 271 < x-correlation-id: 8c4cfeb4-6d2a-491c-b201-74773d9de3db
Authentication errors (HTTP Status 401)
curl -X POST \ -H "Content-Type: application/json" \ -H "x-api-version: 1" \ -d '{"reference": "Test-Echo-Request-01"}' \ https://integrations.uat.controlant.com/api/echo < HTTP/1.1 401 Unauthorized < Date: Tue, 18 Feb 2024 12:55:13 GMT < Server: Kestrel < Content-Length: 0 < WWW-Authenticate: APIKey error=No APIKey authentication header value found < x-correlation-id: 2dd695d3-69ed-44b5-8894-472abcafab01
Unexpected Server errors (HTTP Status 500 and 504)
The Integration API declares two possible error states that can be returned for unexpected server-side errors. Both of these scenarios share the same message format.
curl -X POST \ -H "Authorization: APIKey MYAPIKEY" \ -H "Content-Type: application/json" \ -H "x-api-version: 1" \ -d '{"reference": "500 Error"}' \ https://integrations.uat.controlant.com/api/echo < HTTP/1.1 500 Internal Server Error < Date: Tue, 18 Feb 2024 13:18:42 GMT < Content-Type: application/json < Server: Kestrel < Transfer-Encoding: chunked < x-correlation-id: 9652c916-6caf-4aae-97a9-a07ca92a81e6