Responses

Response format and status codes common to all endpoints

Unless a page says otherwise, every response body is a JSON object with two fields:

{
    "message": "Success",
    "data": { }
}

• message - describes the result of the operation
• data - the requested or resulting object, or null when there is nothing to return

Status codes

• Success
  • Status code: 200 OK
  • message: describes the operation, for example Success or Successfully added the user.
  • data: the object in its new state, an array, or null
• Generic client error
  • Status code: 400 Bad Request
  • message: the error, for example Could not parse payload: ... for malformed JSON
  • data: null
• Authorization error
  • Status code: 401 Unauthorized
  • Missing or invalid token: the body is plain text, Missing token or Invalid token
  • Otherwise a JSON object with message describing the issue, for example Insufficient permission or Failed to log in, and data: null
• Not found
  • Status code: 404 Not Found
  • message: describes what was not found
  • data: null
• Conflict
  • Status code: 409 Conflict
  • message: describes the conflicting value, for example The username already exists: admin
  • data: null
• Validation error

  • Status code: 422 Unprocessable Entity

  • message: Validation errors: <key> - <constraint description>, one entry per failed field

  • data: object with an errors array:

    {
        "message": "Validation errors: username - Usernames should be in lowercase, can only start with letters followed by numbers or underscore. Should be between 1 and 32 characters.",
        "data": {
            "errors": [
                {
                    "path": "/",
                    "key": "username",
                    "message": "Usernames should be in lowercase, can only start with letters followed by numbers or underscore. Should be between 1 and 32 characters.",
                    "constraint": "username_constraint"
                }
            ]
        }
    }

    • path - JSON pointer to the object that holds the failed field
    • key - the failed field
    • message - description of the constraint
    • constraint - name of the constraint
• Generic server error
  • Status code: 500 Internal Server Error
  • message: the error message
  • data: null

Back to Index