Error response structure
{
"message": "Failed to send a message because more than 24 hours have passed since the customer last replied",
"type": "ERROR_TYPE_DEADLINE_EXCEEDED",
"code": "ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOW",
"userTitle": "Failed to send a message because more than 24 hours have passed since the customer last replied",
"userMessage": "Pass along the connectly trace id 'cnct_trace_id' to the team for more information.",
"cntTraceId": "11824978358485860716",
"details": {}
}
| Field | Description |
|---|---|
message | Human-readable description of the error. |
type | Broad error category. See Error types below. |
code | Specific error code identifying the exact failure. See Error codes below. |
userTitle | Expanded error description suitable for display. |
userMessage | Troubleshooting instructions. |
cntTraceId | Connectly trace ID. Include this when filing a support request — it lets Connectly engineers locate the exact failed request. |
details | Additional structured detail, when available. |
Error codes
| Code | Cause |
|---|---|
ERROR_CODE_INVALID_SENDER_ID | The phone number used as the sender is not valid. |
ERROR_CODE_PHONE_NUMBER_BAD_FORMAT | The recipient phone number is in an incorrect format. |
ERROR_CODE_MESSAGE_ATTACHMENTS_NUMBER_INVALID | Invalid number of attachments. Connectly supports only one attachment per message. |
ERROR_CODE_MESSAGE_TEXT_EMPTY | The message text field is empty. |
ERROR_CODE_MESSAGE_TEMPLATE_NOT_FOUND | No template found matching the specified name and language. Create and approve the template first. |
ERROR_CODE_MESSAGE_TEMPLATE_INPUT_INVALID | The template inputs provided are not valid. |
ERROR_CODE_MESSAGE_ATTACHMENT_EMPTY | The attachment URL field is empty. |
ERROR_CODE_MESSAGE_ATTACHMENT_INVALID | The attachment URL is invalid and cannot be parsed. |
ERROR_CODE_BUSINESS_MISSES_MATCHING_CHANNEL | The business account is missing a sender channel of the required channel type. |
ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOW | More than 24 hours have passed since the customer last messaged you. Use the template message API instead. |
ERROR_CODE_BUSINESS_REACHED_LIMITS | The business has reached messaging restrictions on this channel — too many previous messages were blocked or flagged as spam. |
ERROR_CODE_MESSAGE_SELF_INVALID | This message type cannot be sent to yourself. Use a different recipient. |
ERROR_CODE_MESSAGE_PHONE_NUMBER_INVALID | The recipient phone number is invalid. |
ERROR_CODE_MESSAGE_CUSTOMER_OPTED_OUT | The customer has opted out of receiving template messages. |
ERROR_CODE_MESSAGE_CUSTOMER_NO_CONVERSATION_INITIATION | You cannot use the session message API when the customer has not sent the first message. Use the template message API to reach out first. |
ERROR_CODE_BUSINESS_KEY_SECRET_ABSENT | The business API secret has not been initialized. Contact the Connectly team. |
ERROR_CODE_MESSAGE_TEMPLATE_DELETED | New language content cannot be added while existing language content is being deleted. Try again in 4 weeks, or create a new template. |
ERROR_CODE_MESSAGE_TEMPLATE_INVALID_PARAM | An invalid template parameter was provided. Check that all variables, buttons, and parameters are present and correct. |
ERROR_CODE_BUSINESS_RATE_LIMIT_REACHED | The business has exceeded the API rate limit. |
Error types
Error types represent broad categories. Usetype to determine the right corrective action before inspecting the specific code.
| Type | Meaning |
|---|---|
ERROR_TYPE_UNSPECIFIED | Unexpected error. Contact the Connectly team with your cntTraceId. |
ERROR_TYPE_AUTHENTICATION | Invalid authentication credentials — missing or invalid API key. |
ERROR_TYPE_AUTHORIZATION | No authorization for the resource — e.g. the API key doesn’t have access to the specified businessId. |
ERROR_TYPE_RATE_LIMIT | API rate limit exceeded. Wait before retrying. |
ERROR_TYPE_INVALID_REQUEST | Request payload is not valid. Refer to the API docs and fix the request body. |
ERROR_TYPE_DEADLINE_EXCEEDED | Request timed out. Contact the Connectly team with your cntTraceId. |
ERROR_TYPE_NOT_FOUND | The requested resource does not exist. |
ERROR_TYPE_CONFLICT | The resource already exists — use an update operation instead of create. |
ERROR_TYPE_CONTEXT_CANCLED | The client cancelled the request. Check your HTTP client timeout settings and increase the limit. |
ERROR_TYPE_BUSINESS_LIMIT | The business has reached its account-level limits. |