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

# Errors

> Error taxonomy and response shape

## Error response shape

All errors follow a consistent structure:

```json theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "message": "The 'from' field is required.",
    "param": "from"
  },
  "request_id": "req_a1b2c3d4e5f6"
}
```

| Field        | Description                                               |
| ------------ | --------------------------------------------------------- |
| `type`       | Error category (see below)                                |
| `code`       | Machine-readable error code                               |
| `message`    | Human-readable explanation                                |
| `param`      | The parameter that caused the error (when applicable)     |
| `request_id` | Unique ID for debugging. Include this in support requests |

## Error types

### `authentication_error` (401)

The request could not be authenticated.

| Code              | Meaning                                                 |
| ----------------- | ------------------------------------------------------- |
| `missing_api_key` | No `Authorization` header provided                      |
| `invalid_api_key` | Key format is wrong, key is revoked, or key has expired |

### `authorization_error` (403)

The API key is valid but lacks permission.

| Code                     | Meaning                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `insufficient_scope`     | The key doesn't have the required scope for this endpoint                              |
| `line_not_accessible`    | The key is line-scoped and can't access the requested line                             |
| `sandbox_not_activated`  | Your sandbox hasn't been activated yet. Text the activation code to the sandbox number |
| `sandbox_requires_owner` | The sandbox key isn't tied to a Messages.dev account                                   |

### `invalid_request_error` (400)

The request is malformed or missing required data. A small number of
`invalid_request_error` codes are returned with `403` instead of `400` because
they describe a per-line policy violation, not a malformed payload — see
[`contact_has_not_messaged`](#contact-first) below.

| Code                         | Status | Meaning                                                                                                                             |
| ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `missing_required_parameter` | 400    | A required query parameter or body field is missing                                                                                 |
| `invalid_parameter_value`    | 400    | A parameter has an invalid value (e.g. wrong ID prefix or more than one attachment)                                                 |
| `invalid_json`               | 400    | The request body is not valid JSON                                                                                                  |
| `empty_file`                 | 400    | `POST /v1/files` was called with a zero-byte body                                                                                   |
| `advanced_features_required` | 400    | The line you're sending from doesn't have advanced features enabled (required for audio messages, reactions, typing, read receipts) |
| `sandbox_contact_mismatch`   | 400    | You can only send to your paired phone number on the sandbox line                                                                   |
| `contact_has_not_messaged`   | 403    | The recipient (or group chat) hasn't messaged your line first — see below                                                           |

#### Contact-first

Outside the sandbox, the recipient must message your line first before you
can send to them. Sending into a cold contact returns
`contact_has_not_messaged` with HTTP 403. The same rule applies to group
chats: at least one inbound message must have been received in the chat
before you can post to it.

### `not_found_error` (404)

The requested resource doesn't exist.

| Code                    | Meaning                                                   |
| ----------------------- | --------------------------------------------------------- |
| `line_not_found`        | No line exists with the given handle                      |
| `chat_not_found`        | No chat found for the given identifier on this line       |
| `message_not_found`     | No message found with the given ID (including `reply_to`) |
| `outbox_item_not_found` | No outbox item found with the given ID                    |
| `webhook_not_found`     | No webhook found with the given ID                        |
| `file_not_found`        | No file found with the given `file_...` ID                |

### `rate_limit_error` (429)

Too many requests. Back off and retry after the `Retry-After` header value.

| Code                     | Meaning                                                            |
| ------------------------ | ------------------------------------------------------------------ |
| `rate_limit_exceeded`    | Hourly API rate limit exceeded                                     |
| `sandbox_quota_exceeded` | Daily sandbox limit of 50 messages reached. Resets at midnight UTC |

See [Limits](/scaling/limits) for the per-line message guidance that sits
above the API request rate.

## HTTP status codes

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| 200    | Success                                                              |
| 201    | Resource created                                                     |
| 204    | No content (OPTIONS preflight)                                       |
| 400    | Bad request                                                          |
| 401    | Unauthorized                                                         |
| 403    | Forbidden                                                            |
| 404    | Not found                                                            |
| 429    | Rate limited (hourly API rate limit or daily sandbox quota exceeded) |