Error code catalog

Common API errors and recommended handling actions.

Use this catalog to handle common failures consistently.

Validation and request errors

Status	Example detail	What it means	Action
`400`	`channel_id is required`	Required field missing	Fix request payload
`400`	`to is required`	Recipient field missing	Add destination number
`400`	`type is required`	Message operation type missing	Add `type`
`400`	`content is required`	Message content missing	Add `content` object
`400`	`invalid messageID`	Path ID is not valid UUID	Send valid UUID
`400`	`invalid conversation_id`	Body conversation ID invalid	Fix ID format

Status	Example detail	What it means	Action
`401`	`missing user context`	No valid auth credential	Send `X-Api-Key` header
`401`	`invalid email or password`	Login credentials invalid	Re-check login input
`403`	`forbidden`	Credential lacks permission	Use credential with required scope/role

Status	Example detail	What it means	Action
`404`	`message not found`	Resource does not exist	Verify identifier and tenant context
`409`	`conflict`	Request conflicts with current state	Refresh state, then retry safely
`429`	`rate limited`	Limit exceeded	Backoff and retry
`500`	`internal server error`	Unexpected backend failure	Retry with backoff and log request context

{
  "title": "Bad Request",
  "status": 400,
  "detail": "channel_id is required"
}