Errors & Responses

Http Status Codes

Our API attempts to return appropriate HTTP status codes for every request.

Code	Text	Description
200	OK	When the API returns a 200 status code means that the request is completed successfully.
400	Bad Request	The request was invalid or cannot be otherwise served. Please review your input.
401	Unauthorized	Authentication credentials were either missing, incorrect or expired.
404	Not Found	Returned when the requested method is not found. Please review your request.
429	Too Many Requests	Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource.
500	Internal Server Error	Something is broken. Please let us know by creating a support ticket. In most of the case a DebugID will be included in the response message. When available add the DebugID in the ticket description.

Error Messages

When the API returns error messages it provides error data which can be used to better understand the problem. The error data provided with the error message can vary depending on the type of error occured. Currently the API manages to return the following error data types:

Fields: This type of error data is returned in case one or more input parameters are either not in the correct format or available.
Security: This type of error data is returned when there was a problem during the authentication process.
Scopes: This type of error data is returned when the request has been blocked due to a missing scope. To know more about scope please check the scopes page.
Operation: This type of error data is returned when the request cannot be completed but the system can identify the problem.
BadRequest: This type of error data is returned when the request cannot be completed because of an issue with the request.

Error Codes

Each datatype returned in the error has its own unique error code. These codes can be used to make your own localizations. Please check the error codes page for all error codes.

Samples

When the API returns error messages, it does so in your requested format. For example an error from a JSON request could look like this:

Fields error data type

{
  "Message": "One or more input field(s) are not in the correct format or not available. For more information, please check the error data.",
  "ErrorData": {
    "Type": "fields",
    "Fields": [
      {
        "Name": "UserID",
        "Messages": [
          "Value must be a valid integer and bigger than zero."
        ],
        "Code": "Min_Value_Not_Met"
      }
    ]
  }
}

Security error data type

{
  "Message": "Authorization has been denied for this request. For more information please check the error data.",
  "ErrorData": {
    "Type": "security",
    "Details": {
      "Name": "Authentication",
      "Message": "Access_Token not valid or expired. User must login again to get a valid access_token.",
      "Code": "Access_Token_Not_Valid"
    }
  }
}

Scopes error data type

{
 "Message": "One or more scope(s) were missing. Authorization has been denied for this request. For more information, please check the error data."
  "ErrorData": {
    "Type": "scopes",
    "Scopes": [
      {
        "Name": "account_communications",
        "Messages": "This scope is missing.",
        "Code": "Scope_Missing" 
      },
      {
        "Name": "userId",
        "Messages": "This scope is missing.",
        "Code": "Scope_Missing"       
      }
    ]
  }
}

Operation error data type

{
  "Message": "A general error occurred and it was not possible to complete the request. For more information please check the error data."
  "ErrorData": {
    "Type": "operation",
    "Details": {
      "Name": "Get Movie Details",
      "Message": "The movie to view parameter points to a movie file that does not exist or belongs to an inactive member.",
      "Code": "Movie_Not_Found_Or_Inactive_User"
    }
  }
}

BadRequest error data type

{
  "Message": "This request is invalid. For more information, please check the error data.",
  "ErrorData": {
    "Type": "badrequest",
    "Details": {
      "Message": "This accept header is not valid. Please clear the accept header or use 'application/json'.",
      "Code": "Invalid_Accept_Header"
    }
  }
}

Internal Server Error

When encountering an Internal Server Error we try to give as much information as possible.

{
  "Message": "An internal error occurred while trying to complete the request. For more information, please check the error data.",
  "ErrorData": {
    "Type": "internalServer",
    "Details": {
      "Message": "An unexpected error occured while the user was trying to add a new member in a hotlist. OwnerID:[1], UserID:[1], ListID:[1]",
      "Code": "Unknown_Internal_Server_Error_AddUserHotlist"
    }
  }
}

When we are not able to give the detailed information we are returning the following model:

{
  "Message": "An internal error occurred while trying to complete the request. Please try again, or contact us including the DebugID."
  "DebugID": 123456
}