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 | text is required for type=text | Typed payload missing for selected message type | Add text for type=text |
400 | image.url is required for type=image | Image URL missing in typed payload | Add image.url |
400 | invalid messageID | Path ID is not valid UUID | Send valid UUID |
400 | invalid conversation_id | Body conversation ID invalid | Fix ID format |
Auth and permission errors
| 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 |
Resource and state errors
| 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 |
{
"error": {
"code": "validation_error",
"message": "text is required for type=text",
"details": [
{
"field": "text",
"reason": "required"
}
]
},
"request_id": "req_123"
}
For /v1/messages*, error responses use { error, request_id }. Some non-message endpoints still use Huma problem+json.