Responses

Success responses

In case of a success, a specific dataset in form of JSON is returned for the specific endpoint.
Regardless if an endpoint shows domain data, data can be specialized for each endpoint individually.

When a response is 204 or redirection, the response body is an empty json.

Error responses

In case of any error, the response always has a response message and code.

Example:

{
  "message": "ROUTE_NOT_FOUND",
  "code": 404
}

Generic response code for the request is one of the codes presented here.

On the other hand, the code in the response body (JSON payload) is usually from the same generic list, but can also be an internal code if necessary.

The message in the response body is a system message which can be mapped to specific object on the client side and then handled as such.

Some error response will implement the HasData interface, meaning that there will also be a data parameter present in the body. This will be explained for each response individually.

ROUTE_NOT_FOUND

code: 404
You are trying to hit an endpoint which doesn't exits.

UNAUTHORIZED

code: 401
You are not logged in or your login has expired. You need to properly authorize before performing this request.

CSRF_ERROR

code: 400
There is an issue with your CSRF token. It is either missing or is not valid.

UNHANDLED_EXCEPTION

code: 500
Application failed do to an unknown reason.

VALIDATION_EXCEPTION

code: 400
Some of your input parameters did not pass the validation rules for the specific endpoint.

This exception implements the HasData interface, so it will contain the data parameter in the body to determine what went wrong.

For this scenario, data parameter can contain following:

Rule name	Entry explanation
missing	contains names of parameters which are missing in the request
invalid	contains key:value pairs where key is the parameter name and value is the broken rule for that parameter
must	contains key:value pairs where value is the name of the parameter which is missing because the parameter named key was sent in the request
must_not	contains key:value pairs where value is the name of the parameter which shuold not be in the request because the parameter named key was sent in the request
or_requires	contains key:value pairs where key and value are parameters which are dependent. If one parameter appears, the other one must appear as well.
require_if_equal	contains key:value pairs where parameter named key must appear if the parameter named value is equal to a specific value
different	contains key:value pairs where key and value are names of parameters which must have different values

Examples:

Rule name	Error	Explanation
missing	"missing": [ "username" ]	Parameter username is missing.
invalid	"invalid": { "username" : "EMPTY_STRING_VALUE" }	Parameter `username is empty.
must	"must": { "param_one": "param_two" }	Parameter param_one is in the request. param_two must appear along with param_one but it is missing.
must_not	"must_not": { "param_one": "param_two" }	Parameter param_one is in the request. param_two must not appear along with param_one but it is in the request as well.
or_requires	"or_requires": { "param_one": "param_two" }	Parameters param_one and param_two are both missing from the request and at least one of them must be present.
require_if_equal	"require_if_equal": { "param_one" : "param_two" }	Lets say for this example that validation in the API was set that if param_two has a vlaue 10 than param_one must be present in the request
different	"different": { "param_one": "param_two" }	Parameter param_one is the same as param_two but should be different.

Full example:

{
  "message": "VALIDATION_EXCEPTION",
  "code": 400,
  "data": {
    "missing": [
      "param_required"
    ],
    "invalid": {
      "param_invalid_non_empty_string": "EMPTY_STRING_VALUE"
    },
    "must": {
      "param_one": "param_must_go_with_one"
    },
    "must_not": {
      "param_two": "param_must_not_go_with_two"
    },
    "or_requires": {
      "param_three": "param_four"
    },
    "require_if_equal": {
      "param_require_if_five_equal_10": "param_five"
    },
    "different": {
      "param_different_from_original": "param_original"
    }
  }
}

TOO_MANY_REQUESTS

code: 429

The rrequest you tried has reached a max atempt fails. You need to cooldown before you try again.

This exception implements the HasData interface, so it will contain the data.cooldown parameter in the body.
data.cooldown represents the amount of seconds you need to wait before you can try again.

Example:

{
  "message": "TOO_MANY_REQUESTS",
  "code": 429,
  "data": {
    "cooldown": 58
  }
}