> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/build/status-codes-errors/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Status codes and errors messages

> Learn about HTTP status codes and error response formats used by the Middesk API.

The Middesk API is organized around REST. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. Every API response, including errors, returns JSON.

> **Note**
>
> The Middesk API has rate limiting to ensure high performance across all customers. Requests per customer are limited to 20 requests per second.

## Status codes

Middesk uses standard HTTP response codes to indicate the success or failure of an API request.

As a rule of thumb, codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error in the provided information (for example, a required parameter was omitted or a validation error occurred).

Codes in the `5xx` range indicate an error with Middesk servers. These should be extremely rare.

Some `2xx` and `4xx` errors include additional context in the response body.

| Status Code | Meaning                                                                              |
| ----------- | ------------------------------------------------------------------------------------ |
| 200         | OK - Everything worked as expected.                                                  |
| 201         | The object was created.                                                              |
| 202         | The request was accepted.                                                            |
| 400         | Bad Request - The request was unacceptable.                                          |
| 401         | Unauthorized - An invalid API key was provided.                                      |
| 404         | Not Found - The requested resource does not exist.                                   |
| 422         | Validation - A parameter was not formatted correctly.                                |
| 429         | Too Many Requests - An account has sent too many requests in a given amount of time. |
| 500         | Internal Server Error - Middesk encountered an internal server error.                |

## Error messages

When Middesk encounters an error processing a request, Middesk returns a `4xx` or `5xx` status code and a JSON response containing information about the error. The `errors` array contains one or more Error objects.

Each Error object contains a `message` field explaining the error. Some Error objects contain an optional `parameter` field that highlights what specific field caused the error.

**`Example error response from POST /v1/businesses`**

```json title="Example error response from POST /v1/businesses"
{
  "errors": [
    {
      "message": "Name is required",
      "parameter": "name"
    },
    {
      "message": "Address line1 is required",
      "parameter": "address.address_line1"
    }
  ]
}
```

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Learn about HTTP status codes and error response formats used by the Middesk API.