Errors and HTTP Status Codes

Error envelope

{
  "error": {
    "code": "validation",
    "message": "Missing required field: phone"
  }
}

Status	Meaning
`200`	OK
`201`	Created
`202`	Accepted (queued / asynchronous)
`400`	Validation error / bad request
`401`	Missing or invalid API key
`403`	Disallowed scope, IP, or partner
`404`	Resource not found
`422`	Semantic validation error (for example, form fields)
`429`	Rate limit
`500`	Server error

Code	Description
`unauthorized`	Invalid API key or token
`forbidden`	Missing scope, denied IP, or wrong partner
`validation`	Invalid request body
`not_found`	Unknown ID, phone number, or template
`blocked`	Account has opted out
`bot_error`	Flow or bot engine error

State	Meaning
`queued`	Accepted, not yet fully delivered
`sending`	Sending in progress
`delivered`	Delivered to the channel / in-app
`read`	Read by the user (when tracked)
`failed`	All channels failed
`expired`	Expired

Reusing an idempotency_key returns the original message with 200 instead of creating a duplicate.