Skip to main content
When a Connectly API call fails, the response body contains a structured JSON object that tells you exactly what went wrong.

​
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": {}
}
FieldDescription
messageHuman-readable description of the error.
typeBroad error category. See Error types below.
codeSpecific error code identifying the exact failure. See Error codes below.
userTitleExpanded error description suitable for display.
userMessageTroubleshooting instructions.
cntTraceIdConnectly trace ID. Include this when filing a support request — it lets Connectly engineers locate the exact failed request.
detailsAdditional structured detail, when available.

​
Error codes

CodeCause
ERROR_CODE_INVALID_SENDER_IDThe phone number used as the sender is not valid.
ERROR_CODE_PHONE_NUMBER_BAD_FORMATThe recipient phone number is in an incorrect format.
ERROR_CODE_MESSAGE_ATTACHMENTS_NUMBER_INVALIDInvalid number of attachments. Connectly supports only one attachment per message.
ERROR_CODE_MESSAGE_TEXT_EMPTYThe message text field is empty.
ERROR_CODE_MESSAGE_TEMPLATE_NOT_FOUNDNo template found matching the specified name and language. Create and approve the template first.
ERROR_CODE_MESSAGE_TEMPLATE_INPUT_INVALIDThe template inputs provided are not valid.
ERROR_CODE_MESSAGE_ATTACHMENT_EMPTYThe attachment URL field is empty.
ERROR_CODE_MESSAGE_ATTACHMENT_INVALIDThe attachment URL is invalid and cannot be parsed.
ERROR_CODE_BUSINESS_MISSES_MATCHING_CHANNELThe business account is missing a sender channel of the required channel type.
ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOWMore than 24 hours have passed since the customer last messaged you. Use the template message API instead.
ERROR_CODE_BUSINESS_REACHED_LIMITSThe business has reached messaging restrictions on this channel — too many previous messages were blocked or flagged as spam.
ERROR_CODE_MESSAGE_SELF_INVALIDThis message type cannot be sent to yourself. Use a different recipient.
ERROR_CODE_MESSAGE_PHONE_NUMBER_INVALIDThe recipient phone number is invalid.
ERROR_CODE_MESSAGE_CUSTOMER_OPTED_OUTThe customer has opted out of receiving template messages.
ERROR_CODE_MESSAGE_CUSTOMER_NO_CONVERSATION_INITIATIONYou 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_ABSENTThe business API secret has not been initialized. Contact the Connectly team.
ERROR_CODE_MESSAGE_TEMPLATE_DELETEDNew 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_PARAMAn invalid template parameter was provided. Check that all variables, buttons, and parameters are present and correct.
ERROR_CODE_BUSINESS_RATE_LIMIT_REACHEDThe business has exceeded the API rate limit.

​
Error types

Error types represent broad categories. Use type to determine the right corrective action before inspecting the specific code.
TypeMeaning
ERROR_TYPE_UNSPECIFIEDUnexpected error. Contact the Connectly team with your cntTraceId.
ERROR_TYPE_AUTHENTICATIONInvalid authentication credentials — missing or invalid API key.
ERROR_TYPE_AUTHORIZATIONNo authorization for the resource — e.g. the API key doesn’t have access to the specified businessId.
ERROR_TYPE_RATE_LIMITAPI rate limit exceeded. Wait before retrying.
ERROR_TYPE_INVALID_REQUESTRequest payload is not valid. Refer to the API docs and fix the request body.
ERROR_TYPE_DEADLINE_EXCEEDEDRequest timed out. Contact the Connectly team with your cntTraceId.
ERROR_TYPE_NOT_FOUNDThe requested resource does not exist.
ERROR_TYPE_CONFLICTThe resource already exists — use an update operation instead of create.
ERROR_TYPE_CONTEXT_CANCLEDThe client cancelled the request. Check your HTTP client timeout settings and increase the limit.
ERROR_TYPE_BUSINESS_LIMITThe business has reached its account-level limits.