Tabula uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing or in the wrong format), and codes in the 5xx range indicate an error with the Tabula server.

Common error codes

200 - OK	Everything worked as expected.
400 - Bad Request	Usually a missing or malformed parameter.
401 - Unauthorized	HTTP authentication failed
402 - Request Failed	Parameters were valid but the request failed.
403 - Forbidden	The user was authenticated successfully but doesn't have permission to perform the request.
404 - Not Found	The resource doesn't exist. This can also happen if the Content-Type of the request isn't set to application/json
500, 502, 503, 504 - Server Errors	Something went wrong on the Tabula end.

Authentication errors

If the OAuth or Basic Auth request is invalid, Tabula will return an HTTP 401 Unauthorized response with the following JSON:

{
  "success": false,
  "status": "unauthorized",
  "errors": [
    {
      "message": "API requests must be authenticated with HTTP Basic Auth or OAuth"
    }
  ]
}

Bad Request errors

Tabula returns errors for bad requests in a standard format that displays the individual fields that have errors, so that you could, for example, but the error next to the applicable form field. These errors are returned in two parameters, result which maps individual fields to the primary error message, and errors which gives a full list of each field and error. Errors that do not pertain to a particular field will not have the field key. The HTTP status code will be 400 Bad Request.

Example:

{
  "success": false,
  "status": "bad_request",
  "result": {
    "academicYear": "I don't recognise this"
  },
  "errors": [
    {
      "field": "academicYear",
      "message": "I don't recognise this"
    },
    {
      "field": "academicYear",
      "message": "You need to put something here."
    }
  ]
}

Permission denied errors

If the API user doesn't have permission to perform the request, Tabula will return an HTTP 403 Forbidden and a standard JSON error:

{
  "success": false,
  "status": "forbidden",
  "errors": [
    {
      "message": "User cuscav can't perform MonitoringPoints.Report on Department(xxx)"
    }
  ]
}

Not found errors

If a required entity in the request isn't found, Tabula will return an error in a standard format indicating the parameter type of the not-found item, with HTTP status code 404 Not Found and the standard JSON error format:

{
  "success": false,
  "status": "not_found",
  "errors": [
    {
      "message": "Item not found of type Department"
    }
  ]
}