On error, the Kudoz API returns a response with a HTTP status code in the 4xx or 5xx ranges and an error resource body. The error resource contains error messages that provide information on the error context.

Example: A response with the HTTP status code 422 Unprocessable entity and the following body:

{
  "errors": {
    "email": ["taken"],
    "password": ["too_short:6"],
    "profile": {
      "age": ["less_than:13"]
    }
  }
}

Error HTTP Status Codes

HTTP status codes are part of Kudoz API’s contract. Clients should rely only on the returned status codes to deduce request success or failure. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a client error i.e. an error related to the request itself (e.g. a missing parameter, an out of range value, etc.), and codes in the 5xx range indicate an error with Kudoz’s own servers.

Here is the list of the HTTP status codes in case of client error:

  • 401 Unauthorized is returned when the request did not include valid authentication credentials in the Authorization HTTP header. The client may repeat the request with a new or replaced authorization data.
  • 404 Not Found is returned when the client attempts to access a non-existing or a non-authorized resource. For security reasons, no distinction is made between access to non-existing and unauthorized access.
  • 400 Bad Request is returned for malformed requests which do not conform to the structure expected by the server. This error is typically raised for requests where required parameters are missing.
  • 422 Unprocessable entity is returned when the request is well-formed but the instructions cannot be processed by the server du to semantic errors. For instance, requests containing invalid parameters values.
  • 429 Too Many Requests is returned when an API client exceeds its access rate quota. Please refer to your contract or liaise with our support to understand your quota limits.

Error Resources

On client errors, the Kudoz API return a JSON resource to describe the failure. The error resource has a root field errors with an error details object as value. Each offending request parameter is mapped to an array of error messages that it has triggered.

A special parameter base is added to the error object if one or more errors have occurred but cannot be directly related to a particular parameter.

The error response body contains a json resource with the following layout:

{
  "errors": {
    "base": ["error_message_1", "error_message_2", ...],
    "parameter_1": ["error_message_3", "error_message_4", ...],
    "parameter_2": ["error_message_5", "error_message_6", ...],
    ...
  }
}

In case of nested input parameters objects where one or more request parameters values are hashes (as opposed to arrays or plain scalar values like integer, strings etc.), the error object reflects the same nesting structure. In this case, the error response body would have the following layout:

{
  "errors": {
    "base": ["error_message_1", "error_message_2", ...],
    "parameter_1": ["error_message_3", "error_message_4", ...],
    "parameter_2": ["error_message_5", "error_message_6", ...],
    ...
    "nested_parameter_1": {
      "parameter_1_1": ["error_message_7", "error_message_8", ...],
      "parameter_1_2": ["error_message_9", "error_message_10", ...],
      ...
    },
    ...
  }
}

See examples below.

Error Messages

Error messages are composed of two parts:

  1. The message prefix is an error identifier composed of lower case alphabetic and the underscore _ characters.
  2. An optional suffix: the error data. It contains additional data to clarify the error context. It is composed of colon : separated alphanumeric with underscore values.

The error message has the following format could be parsed with the following regular expression:

\A(?<error-identifier>[_a-z]+)(?<error-data>(?::\w+)*)\z

The Kudoz API defines the following common errors messages to handle common errors that apply to all its routes. Please refer to the specific route’s documentation for the additional specific list of error messages.

  • missing: required parameter is missing.
  • invalid: parameter value violates required parameter constraints.
  • blank: parameter value should not be empty or blank.
  • taken: desired value is already taken.
  • inclusion: parameter value is not included in the list of permitted values.
  • not_a_number: parameter value should be a number.
  • not_an_integer: parameter value should be an integer.
  • greater_than:{max_value}: parameter value is greater than the maximum value max_value.
  • greater_than_or_equal_to:{max_value}: parameter value is greater than or equal to the maximum value max_value.
  • less_than:{min_value}: parameter value is less than the minimum value min_value.
  • less_than_or_equal_to{min_value}: parameter value is less than or equal to the minimum value max_value.
  • too_long:{max_length}: parameter value string length is greater than max_length.
  • too_short:{min_length}: parameter value string length is less than min_length.
  • quota_exceeded: too many API calls.
  • unauthorized: the API authentication failed.
  • not_found: requested resource is not found.

Examples

To illustrate the error codes and messages illustrated above, let’s take as example a (fictional) user sign up API endpoint:

POST /signup

Parameters:

  • email: required, must be a valid email
  • password: required, must be at least 6 characters long.
  • profile: optional, an object describing the user.
  • age: optional, must be an integer greater than or equal to 13.

Missing Parameter

Request

Body:

{
  "password": "my_secure_password"
}

Response

HTTP code 400.

Body:

{
  "errors": {
    "email": [ "missing" ]
  }
}

Invalid Parameter

Request

Body

{
  "email": "@invalid@",
  "password": "123"
}

Response

HTTP code 422.

Body:

{
  "errors": {
    "email": [ "invalid" ],
    "password": [ "too_short:6" ]
  }
}

Invalid Nested Parameter

Request

Body:

{
  "email": "joe@example.com",
  "password": "123",
  "profile": {
    "age": 6
  }
}

Response

HTTP code 422.

Body:

{
  "errors": {
    "password": [ "too_short:6" ],
    "profile": {
      "age": ["less_than:13"]
    }
  }
}