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, authentication, and that your account holds the role/permission required for the endpoint — 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 CMS Admin 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, authentication, and permissions.
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.

403 Forbidden

Returned when the authenticated user does not have the role or permission required for the requested action — for example, a user without the Case Raffle permission attempting to raffle a case, or a non-Super Admin attempting to delete a system role.

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.

429 Too Many Requests

Returned when a rate-limited endpoint is exceeded — most notably POST /login, which is limited to 3 attempts/hour per email + IP.

401 Unauthenticated

{
  "message": "Unauthenticated."
}

403 Forbidden

{
  "message": "This action is unauthorized."
}

422 Validation Error

{
  "message": "The case title field is required.",
  "errors": {
    "case_title": [
      "The case title field is required."
    ],
    "counsel_email": [
      "The counsel email has already been taken."
    ]
  }
}

422 Business Logic Error

{
  "message": "Cannot delete a role with assigned users."
}

429 Too Many Requests

{
  "message": "Too many login attempts. Please try again in 3542 seconds."
}

Disabled users

If a user account has been disabled by an administrator (disabled_at is set), all API requests will return a 403 error:

Disabled user response

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