Errors

Error taxonomy and response shape

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)