Legacy API Notice: This documentation covers the Legacy Sent API (v2). For new integrations, please refer to the latest Sent API v3 Error Handling.

Error Reference

The legacy Sent API v2 uses standard HTTP status codes and returns error details in a problem-details JSON format. This page describes the response format and status codes. For a message-by-message lookup with causes and remediation, see the Error Catalog; for retry and error-handling implementation patterns, see How to handle Sent API errors.

Error response format

Error bodies share one structure. Validation errors key the errors object by request field name:

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "phoneNumber": ["Phone number is required"]
  }
}

Field	Type	Description
`type`	String	Link to the RFC 9110 definition of the status code
`title`	String	Human-readable summary of the error
`status`	Integer	HTTP status code, repeated in the body
`errors`	Object	Map of request field name to an array of error messages

Errors that are not tied to a request field appear under the generalErrors key:

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 404,
  "errors": {
    "generalErrors": ["Template not found"]
  }
}

The GET lookup endpoints (contacts, messages, templates, number lookup) return 404 with an empty body instead of a problem-details payload when the resource does not exist.

HTTP status codes

Status Code	Meaning	Returned When
`400`	Bad Request	A required field is missing, an ID is malformed, or a template variable fails validation
`401`	Unauthorized	Authentication headers are missing or invalid
`402`	Payment Required	Account balance is insufficient to send a message
`404`	Not Found	The contact, message, or template does not exist for the authenticated customer
`429`	Too Many Requests	A rate limit was exceeded
`500`	Internal Server Error	An unexpected server-side failure occurred

401 Unauthorized

Authentication failures return one of two titles:

Missing or invalid sender identifier: the x-sender-id header is missing or is not a valid UUID
Invalid or missing API credentials: the x-api-key header is missing, or the key does not match the sender ID

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "Invalid or missing API credentials",
  "status": 401,
  "errors": {
    "generalErrors": ["Invalid or missing API credentials"]
  }
}

402 Payment Required

POST /v2/messages/phone and POST /v2/messages/contact return 402 when the account balance is below the minimum required to send:

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 402,
  "errors": {
    "generalErrors": ["Insufficient balance to send message."]
  }
}

429 Too Many Requests

The v2 send-message endpoints are rate limited per customer account. Limit values, X-RateLimit-* response headers, and the 429 body are documented on Rate Limits.

500 Internal Server Error

500 responses indicate an unexpected server-side failure, for example Failed to queue message for processing. on the send endpoints. The Error Catalog lists the server error messages.