Errors

In this guide, we will discuss what happens when you encounter issues while working with the API. Let's explore the status codes and error formats you might come across.

You can determine if your request was successful by checking the status code in the API response. If the response indicates an error, you can use the error message and validation details to understand what went wrong.

Before reaching out to support with an error, please double-check your request parameters and authentication, as most errors can be resolved with a careful review.

Status codes

Here is a list of the different categories of status codes returned by the Mainframe API.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error — check your request parameters and authentication.
Name
5xx
Description
A 5xx status code indicates a server error.

Common error responses

401 Unauthenticated

Returned when no valid session is present or the session has expired. Re-run the authentication flow to get a fresh session.

403 Forbidden

Returned when the authenticated user does not have permission to perform the requested action — for example, a user without the Payroll Admin role calling a Payroll endpoint, or a user whose account has been disabled by an administrator.

404 Not Found

Returned when the requested resource does not exist.

422 Unprocessable Entity

Returned when validation fails. The response includes an errors object with field-specific error messages. Also returned for business-rule violations that aren't simple field validation.

401 Unauthenticated

{
  "message": "Unauthenticated."
}

403 Disabled account

{
  "message": "Your account has been disabled."
}

422 Validation Error

{
  "message": "The title field is required.",
  "errors": {
    "title": [
      "The title field is required."
    ],
    "resource_organization_id": [
      "The selected resource organization id is invalid."
    ]
  }
}

422 Business Rule Error

{
  "message": "This objective cannot be deleted because it has child objectives."
}

Disabled users

If a user account has been disabled by an administrator, all /api/* requests for that account return a 403 error:

Disabled user response

{
  "message": "Your account has been disabled."
}