The Kompliant Web API makes use a many, but not all HTTP status codes to inform the caller of the result of the request. In addition to HTTP status codes, the errors array in the response will provide more details in most responses.

The Kompliant Web API provides consistent response structures across both application and infrastructure responses. Most responses will include a trace_id in the meta field, which can be invaluable in debugging and investigating unexpected system behaviors. However, certain infrastructure responses may not include the trace_id depending on where in the infrastructure stack the error occurs.

Summary

Details

Success

200

All successful responses will return a 200. The Kompliant Web API does not make use of some other success statuses such as 201 or 202. The reason is because every response will include the meta field to provide some metadata information about the response.

Client Error

For all responses that are a client error, the errors array in the response will contain the details about the error. In all cases, the caller should correct the issues and try the call again, as appropriate.

400

This is used when no other specific client error status code applies such as for authentication, authorization, throttling, or payload size. Typically this error code is used when the request body does not follow the standards for a given API endpoint, such as text in a numeric field.

This code will also be used if the requested URL path does not exist or when an unsupported HTTP method is used. Typically the HTTP status codes 404 and 405 would be used in these two case respectively. However, due to limitations in our API gateway infrastructure, that is not possible.

401

This status will be returned for any failure or errors encountered as part of the authentication process. For example, this status will be returned if any required headers are missing, such as Authentication, X-API-Key, or X-Auth-Token. In addition, if authentication fails, such as because the API Key is not found or the signature does not match, this status will be returned.

403

If authentication succeeds, but authorization fails, this error is returned. For example, if the caller is not allowed to call a certain web method or the caller does not have access to a given entity.

413

If the request is too large, this status is returned. Currently the maximum size of requests is 100 MB.

415

If the media type presented in the Content-Type header is not accepted by the API, this code is used.

429

If the caller makes too many calls in a given amount of time, the system may throttle the caller and return this status code. The caller should slow down the rate of requests.

Server Error

For all responses that are a server error, the errors array in the response will contain the details about the error. These responses typically indicates to the caller that our systems are having temporary problems and should retry the request at a later time.

500

This is used when no other specific server error status code applies.

503

We will use this status to indicate we are performing maintenance.

504

When one of the layers of our system times out in communicating with another layer, this error is returned.