Skip to main content

Error responses and how to handle them

In this section:

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:

Table 57. API error statuses

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