Error Structure

Konsentus uses standard HTTP response status codes (opens new window) to indicate the success or failure of an API request. This document details how the HTTP response codes are used and also the response structure of API errors.

In general, there are three status code ranges you can expect:

• 2xx success status codes confirm that your request worked as expected
• 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
• 5xx error status codes are rare and indicate an error with Konsentus's servers

HTTP status code summary

200 - OK

The request has succeeded.

201 - Created

The request has been fulfilled and has resulted in one or more new resources being created.

400 - Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 - Unauthorized

The request has not been applied because it lacks valid authentication credentials for the target resource.

403 - Forbidden

The server understood the request but refuses to authorize it.

404 - Not Found

The origin server did not find a current representation for the target resource.

405 - Method Not Allowed

The request method is known by the server but has been disabled and cannot be used.

406 - Not Acceptable

The content-type sent with the request is not accepted by the server.

413 - Payload Too Large

Request entity is larger than limits defined by server.

429 - Too Many Requests

The user has sent too many requests in a given amount of time ('rate limiting').

500 - Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

503 - Service Unavailable

The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

Error Attributes

An object with the following attributes is returned for 4XX and 5XX errors.

id string

A unique identifier for this particular occurrence of the problem.

code string

An application-specific error code, expressed as a string value.

title string

A short, human-readable summary of the problem that should not change from occurrence to occurrence of the problem, except for purposes of localization.

link string

A link that leads to further details about this particular occurrence of the problem.

param string (optional)

If the error is parameter-specific, the parameter related to the error is returned.

Each error object is returned within an errors array.

{
  "errors": [{
    "id": string,
    "code": string,
    "title": string,
    "link": string,
    "param": string optional,
  }]
}