The Kompliant Web API uses a standard set of fields in the responses. This standardization makes it easier for developers to handle results more consistently, such as determining if the request succeeded or failed.

Field Definitions

code

A field in the error object or the warning object. The value will be an ENUM string defined either in the Standard Errors documentation or in the API documentation itself.

data

The field that will contain the result of the request as defined by the particular API. If no data is returned, this field will still be returned by contain an empty object.

This field is returned as a top-level field for regular APIs when the meta.status value is SUCCESS.

This field is returned in an individual batch result object, if that result as seen in the status field is SUCCESS.

error

The error object will contain at least two fields: code and message. It may contain other fields as defined by the error (see Standard Errors) or the particular API.

This object will always be a part of the errors array.

errors

An array of error objects to indicated the one or more errors from the request.

This field is returned as a top-level field for regular and batch APIs when the meta.status value is ERROR.

This field is returned in an individual batch result object, if that result as seen in the status field is ERROR.

message

A field in the error object or the warning object. The value will be a plain language description of the error.

meta

The top-level field returned by both regular and batch APIs to provide metadata information about the request and response. It will contain the status field. Usually it will also contain the trace_id and version fields. It may contain the warnings array if there are warnings also included result. It may also contain other fields to provide more information.

request

A field in the result object that is used to correlate the individual batch request with the result. The value of the request object will be one or more of the fields provided in the original individual request. The particular API will define exactly what values are echoed back but it will always be enough to correlate the result.

For example, a request may include an ID and large field of text. The API may document that it will only return the ID as that should be sufficient to correlate the result.

result

The result object will contain fields to indicate the result of a particular request in a batch API call that included multiple requests. The object will contain a status field, a request object, and either a data object or [errors`](doc:response-fields#errors) array.

This object will always be a part of the results array.

results

An array of result objects that indicate the result of one or more requests made as part of a batch API call.

This field is returned as a top-level field for batch APIs when the meta.status value is BATCH_PROCESSED.

status

The status field indicates the result of API request. It can also indicated the result a particular item from a batch API request.

meta.status

When found in the meta object, the statusfield applies to the whole request.

For regular APIs the value can be either SUCCESS or ERROR. When the value is SUCCESS, the HTTP response code will be 200. All other HTTP response codes will mean that the field's value is ERROR.

For batch APIs, the value can be BATCH_PROCESSED or ERROR. The value of BATCH_PROCESSED will be returned with an HTTP response code of 200. All other HTTP response codes will mean that the field's value is ERROR. In addition, BATCH_PROCESSED means that all individual requests in the batch were processed. The results array should be referenced to understand the result (success or error) of each individual item in the batch.

result status

The status field can also be found as part of the result object to indicate whether the individual request succeeded or failed. In this context the status field will be wither SUCCESS or ERROR.

trace_id

The trace_id field is a unique string returned in most API responses, and serves as a critical tool for troubleshooting anomalies and tracking the flow of requests through the system. This value can be supplied back to Kompliant to help debug unexpected system behaviors. While most responses include this field, certain infrastructure-level errors may not include a trace_id depending on where in the system stack they occur.

version

The version field will contain the version of the API executed. It will either match the X-API-Version header sent with the request or will be the latest version.

warning

The warning object will contain at least two fields: code and message. It may contain other fields as defined by the warning (see Standard Errors) or the particular API.

This object will always be a part of the warnings array.

warnings

An array of warning objects to indicated the one or more warnings from the request.

This field is found in the meta field.