> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagedesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes and error body shapes returned by the MessageDesk Developer API.

# Errors

The API uses conventional HTTP status codes. Errors come in two shapes.

***

## Single-message errors

Most failures return an object with one `error` string:

```json theme={null}
{ "error": "workspace not found" }
```

| Status  | Meaning                                                                                                                                      |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **400** | The request couldn't be interpreted, for example malformed JSON.                                                                             |
| **401** | Missing, malformed, or expired bearer token. See [Authentication](/developer/authentication).                                                |
| **402** | The workspace's subscription is inactive or a payment failed. The body also carries a `code` of `subscription_inactive` or `payment_failed`. |
| **403** | The user isn't allowed to act on this workspace or resource.                                                                                 |
| **404** | The workspace or a referenced record doesn't exist.                                                                                          |
| **409** | The record already exists or can't be changed.                                                                                               |
| **500** | Something went wrong on our side. Retry with backoff, and [email support](mailto:support@messagedesk.com) if it persists.                    |

***

## Validation errors

When a request body fails validation the API returns **422** with a **list** of field errors:

```json theme={null}
[
  { "field": "From", "message": "must be a valid phone number" },
  { "field": "Text", "message": "must be at most 1200 characters" }
]
```

<Note>
  **`field` is the field's internal name, not the JSON key.** `From` refers to the `from` property, `MediaURL` to `mediaUrl`, and so on. Fix every entry and resend. Validation stops the request before anything happens, so a 422 never has side effects.
</Note>

An empty or unreadable JSON body returns **422** with a single object instead:

```json theme={null}
{ "message": "invalid JSON (EOF)" }
```