Errors

Error response shape

All errors follow a consistent structure:

{
  "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 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 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)

Getting Started

Guides

Concepts

Scaling

Error response shape

Error types

`authentication_error` (401)

`authorization_error` (403)

`invalid_request_error` (400)

Contact-first

`not_found_error` (404)

`rate_limit_error` (429)

HTTP status codes

​Error response shape

​Error types

​authentication_error (401)

​authorization_error (403)

​invalid_request_error (400)

​Contact-first

​not_found_error (404)

​rate_limit_error (429)

​HTTP status codes

Error response shape

Error types

`authentication_error` (401)

`authorization_error` (403)

`invalid_request_error` (400)

Contact-first

`not_found_error` (404)

`rate_limit_error` (429)

HTTP status codes