Error Guides
Types of errors and their resolutions
Prerequisite
Understanding the data structure of logs
Error stages
Errors can essentially occur at 4 stages when triggering a notification:
-
API Errors: These errors occur at API level
-
Workflow is not processed: SuprSend could not process the workflow due to issues in the workflow or event payload such as the user's
distinct_idis not found in the SuprSend database or missing template information.
- Workflow processed, but notification for one or more channels is not triggered by SuprSend: This type of error occurs from template rendering failures or incorrect/missing channel information in the user profile. Refer section below to debug these errors.
- Vendor didn't accept the sent request or returned delivery failure error: In such cases, you'll see
Trigger failedorFailure by Vendorstatus in the third step of the logs. These errors are passed by the vendor when SuprSend initiates a send call to the vendor. Hover over the 'i' icon to view the error message. For detailed troubleshooting, refer to the individual vendor guides.
API errors
This can happen for two major reasons:
| Failure reason | How to solve? |
|---|---|
| 2 API requests have the same idempotency key. SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If Suprsend receives more than one request with the same idempotency_key in a 24 hour window, it will only process the first request and skip all other requests. Know more about idempotency key here. | Try passing another idempotency key in your workflow or event payload. |
| If workflow is triggered via event and there is no active workflow associated with that event. | Check if there is an active workflow created on SuprSend dashboard with the given event name. If not, Refer documentation to create workflow on SuprSend dashboard. |
Need help debugging? Reach out on Support
If your error isn't covered above, reach out to us on Slack community or via email: [email protected]
Workflow not processed
Workflow errors
Visible inside the workflow tab on logs page.
| Failure reason | How to solve? |
|---|---|
| no user found with distinct_id: <distinct_id> | - If you are triggering notification via event, user needs to be created before hand. Create user profile via API or one of our SDKs. - If you are triggering workflow directly via API, pass user channel information in the user instance of your workflow call. Refer workflow documentation of your respective backend SDK. |
| no active/preferred channels found for user with distinct_id:<distinct_id> | This error would essentially mean that user doesn't have any applicable active channels in their profile. Applicable channel is the subset of template group channel, channels specified in workflow $channels key. This could happen for 2 major reasons:- User doesn't have that channel set in their profile. If the workflow is triggered via event, user's channel is derived from the existing user profile. Create user profile via API or one of our SDKs. - All identities for that channel are inactive in user profile. Channel can be marked inactive using unset or remove function via SDK or API.SuprSend also marks the channel identity inactive for email and whatsapp in case of hard errors from vendor end, such as bounced email addresses, unregistered whatsapp numbers. This is done to safeguard your email domain authority or whatsapp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in whatsapp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for whatsapp and 90 days for email. |
| template: live channels: [channel_array], but no respective user (subscribed-)channels present | User profile doesn't have any active channel from the channels available in template group. This could happen for 2 major reasons: - User doesn't have that channel set in their profile. If the workflow is triggered via event, user's channel is derived from the existing user profile. Create user profile via API or one of our SDKs. - All identities for that channel are inactive in user profile. Channel can be marked inactive using unset or remove function via SDK or API.SuprSend also marks the channel identity inactive for email and whatsapp in case of hard errors from vendor end, such as bounced email addresses, unregistered whatsapp numbers. This is done to safeguard your email domain authority or whatsapp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in whatsapp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for whatsapp and 90 days for email. |
| TemplateGroup <template_slug> not found | This error occurs when, - the template with given template_slug in not present in your workspace. You can search with template_slug using global search ⌘ + K on dashboard to verify this.- there is no published template version available for the channel - you have mistakenly passed template name instead of template slug in your workflow payload. You can get template_slug by clicking on copy icon next to template name on template details page |
| NotificationCategory <category_slug> not found | The notification category passed in workflow payload is not present on SuprSend dashboard or you have mistakenly added category name rather than it's slug. Click on Notification category name to copy the slug. > Please note only published categories can be used in workflows. If you have your category available in draft version, publish the changes before triggering the workflow. Navigate to Settings -> Notification Categories to see all available categories. Click on Category name to copy slug. |
| user not subscribed to category: <category_slug> | User has opted_out from this category. This could happen either if the default user preference for this category is opt_out or if the default preference is opt_in, then user has explicitly opted_out of this category.You can get user preference setting for that particular category using HTTP API. |
| user has unsubscribed from all-channels for category: ** | User has opted_out from this category. This could happen either if the default user preference for this category is opt_out or if the default preference is opt_in, then user has explicitly opted_out of this category.You can get user preference setting for that particular category using HTTP API. |
| no (subscribed-)channels found for user. category: <category_slug> | User has opted_out from this category. This could happen either if the default user preference for this category is opt_out or if the default preference is opt_in, then user has explicitly opted_out of this category.You can get user preference setting for that particular category using HTTP API. |
| brand doesn't exist with id: <brand_id> | The brand_id doesn't exist in the given SuprSend workspace. Check for available brands on SuprSend dashboard -> brands page.You can create this brand from SuprSend dashboard or via your backend SDK / API. |
| NotificationCategory <category_slug> not applicable to tenant/brand <brand_id> | This means that brand's default preference for the category_slug is turned off for brand_id. To check default preference setting of each brand, navigate to default preferences tab on brand details page. |
| recipient: error evaluating jq-expression <recipient_expression>, could not be resolved from event properties | This error occurs when you have overridden the recipient configuration in your workflow, and the jq-expression added in the recipient field is throwing an error or returning null value. To troubleshoot: 1. Navigate to the workflow details page by clicking on the workflow name in the logs. 2. Check the jq-expression added in the recipient field. 3. The recipient jq-expression utilizes event properties JSON for parsing. Validate the output of your jq-expression by adding property JSON here. |
| 500: xxxx | SuprSend Internal server error. Reach out to us on Slack community for assistance with this issue. |
| all channel identities provided for user are invalid | This error can arise when user channels are passed as part of your workflow payload and the format of the channel identity is not correct. Supported format for each channel identity: - SMS, Whatsapp - +15555555555 (country code is mandatory) - Email - [email protected] Refer here for other channel formats. |
| user's distinct_id must be present if it's not transient | This error occurs if user distinct_id key is null or blank in workflow or event payload. The distinct_id is the unique identifier of the recipient and should always be included in the workflow if you are not sending notifications to anonymous users.If you wish to send notification to an anonymous user without providing the distinct_id, include user channels and set is_transient: True in the users key of your workflow payload. Refer doc for more information on sending notification to anonymous users. |
| users - no valid value passed | This error occurs when distinct_id key is not passed in your workflow or event payload. |
| invalid duration-format [TTL duration]. valid format [xx]d[xx]h[xx]m[xx]s | This error occurs when TTL format in the smart delivery block is incorrect. The correct TTL format is [xx]d[xx]h[xx]m[xx]s where d = day, h = hour, m = minute, s = second. For example - 1d2h30m would indicate a Time to live (TTL) is 1 day 2 hours 30 minutes. |
| invalid duration-format . valid format [xx]d[xx]h[xx]m[xx]s | This error occurs when time-duration format in the delay block is incorrect. The correct format is [xx]d[xx]h[xx]m[xx]s where d = day, h = hour, m = minute, s = second. For example - 1d2h30m would indicate a delay of 1 day 2 hours 30 minutes. |
| channel details missing for transient user | It is essential to pass channel identities in users key if you are sending notification to anonymous user with is_transient: True set. You can add channel identity as "$email":["[email protected]"] in your users object. Read more about sending notification to anonymous users here. |
Broadcast errors
Broadcast logs are visible inside broadcast tab on logs page.
| Failure reason | How to solve? |
|---|---|
SubscriberList Broadcast API: subscribers list is empty for list_id:<list_id> | List doesn't have any users added. You can either sync users programmatically via SDK / API or directly via csv upload from dashboard -> Lists page. |
SubscriberList Broadcast API: TemplateGroup <template_slug not found | This error occurs when, - the template with given template_slug in not present in your workspace. You can search with template_slug using global search ⌘ + K on dashboard to verify this.- there is no published template version available for the channel - you have mistakenly passed template name instead of template slug in your workflow payload. You can get template_slug by clicking on copy icon next to template name on template details page. |
| SubscriberList Broadcast API: template: broadcast channels: <channel_array> are not live | This error occurs when none of the channels mentioned in broadcast channels key is published in the template group. |
| SubscriberList Broadcast API: list_id: <list_id> not found | <list_id> doesn't exist in SuprSend. You can create list programmatically via SDK / API or directly by clicking on "New List" button on SuprSend dashboard -> Lists page. |
| SubscriberList Broadcast API: trigger_at must be in ISO 8601 format.... | This error occurs when time-duration format in the trigger_at key is incorrect. The correct format ISO 8601 timestamp. For example - 2024-01-01T05:30:00Z indicates that the notification will be triggered at 1st Jan, 2024 5:30 am UTC. |
| SubscriberList Broadcast API: no vendor configured for channel: <channel_name> and category: <notification_category> and id-provider: <vendor_name> | This happens when vendor configuration for the given channel and notification category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors here. |
Notification not triggered by SuprSend
Workflow errors
Workflow logs are visible inside workflow tab on logs page.
| Failure reason | How to solve? |
|---|---|
<channel>: template rendering failed error: "<variable_key>" not defined in [object Object] | Certain variables with variable_key exist in the template but are not added in workflow data or event properties. |
| <channel_slug>: template rendering error error: Cannot read properties of undefined (reading '0') | This error generally occurs when you are using handlebars helpers in your template on a nested object and the variable referenced inside the helper has parent key missing. For instance, if you have {{default location.city "your place"}} helper in your template, and the workflow data has location key missing, this error will occur. |
| user has unsubscribed from channels <channel_array> for category: <category_slug> | User has opted_out from the given channel list for category_slug.You can get user preference setting for that particular category using HTTP API. |
| no vendor configured for channel: and category: <notification_category> and id-provider: | This happens when vendor configuration for the given channel and notification category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors here. |
Broadcast errors
Broadcast logs are visible inside broadcast tab on logs page.
| Failure reason | How to solve? |
|---|---|
SubscriberList Broadcast API: <channel>: template rendering failed error: "<variable_key>" not defined in [object Object] | Certain variables with variable_key exist in the template but not part of broadcast data or user properties if you are using $user variable in the template. |
| SubscriberList Broadcast API: template: broadcast applicable live channels: [channel_list], but no respective user channels present | User profile doesn't have any active channel from the channels available in template group. This could happen for 2 reasons: - User doesn't have that channel set in their profile. If the workflow is triggered via event, user's channel is derived from the existing user profile. Create user profile via API or one of our SDKs. - All identities for that channel are inactive in user profile. Channel can be marked inactive using unset or remove function via SDK or API.SuprSend also marks the channel identity inactive for email and whatsapp in case of hard errors from vendor end, such as bounced email addresses, unregistered whatsapp numbers. This is done to safeguard your email domain authority or whatsapp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in whatsapp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for whatsapp and 90 days for email. |
Other questions asked on community
- I triggered an event but it doesn't appear in dashboard logs?
We currently do not track individual event trigger currently unless it's associated with a workflow. If you don't see an event trigger in logs, check if there are active workflows linked to that event on SuprSend dashboard. Another reason could be if you are using idempotency key and 2 requests have the same idempotency key. SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If Suprsend receives another request with the same idempotency_key in a 24 hour span, it will skip processing those requests. Know more about idempotency key here.
- I added channels to the user profile, but they are not reflected in subscriber profile on SuprSend dashboard?
Check the format of value passed in user channels. Channel will not be updated in profile if the format is incorrect. Supported format for each channel:
- SMS, Whatsapp -
+15555555555(country code is mandatory) - Email -
[email protected] - Refer here for other channel formats.
If you are facing an issue which is not covered above, reach out to us on Slack community or via email: [email protected]
Updated 7 months ago