Error handling

Our error handling system ensures that you are informed and equipped to address issues that may arise during the message-sending process. Before sending a message, we retrieve the integration property value from the request parameters, which allows us to use it as a destination to return that we have experienced an error with a notification.

In such cases, we provide you with a notification containing detailed information about the error, enabling you to make necessary adjustments and resend the notification successfully to the end user.

The current error handling can include the following fields:
code: A unique identifier that allows you to quickly identify and handle specific types of errors
description: A detailed explanation of the detected error
requestId: A unique identifier for the specific request, which is useful for troubleshooting and tracing errors within the Toqio system.
status: The HTTP status code that best represents the nature of the error

User Center notifications and Admin Center notifications error handling

In the case of a notification involving multiple receivers, our system generates an error notification for each merchant user. We include all original properties provided, along with a list of errors encountered as a string.

The possible errors you may encounter include the following.

Note that the descriptions provided here may be expanded to include more detailed information, such as adding relevant IDs:

UNSPECIFIED_RECEIVERS("unspecified_receivers", "Unspecified receivers", HttpStatus.BAD_REQUEST),
CUSTOM_NOTIFICATION_NOT_DELIVERED("custom_notification_not_delivered", "Custom notification not delivered", HttpStatus.INTERNAL_SERVER_ERROR),
CUSTOM_NOTIFICATION_ERRORS_NOT_DELIVERED("custom_notification_errors_not_delivered", "Custom notification errors not delivered", HttpStatus.INTERNAL_SERVER_ERROR),
UNABLE_TO_MAP_CUSTOM_NOTIFICATION("unable_to_map_custom_notification", "Unable to map notification", HttpStatus.INTERNAL_SERVER_ERROR),
UNABLE_TO_SAVE_CUSTOM_NOTIFICATION("unable_to_save_custom_notification", "Unable to save notification", HttpStatus.INTERNAL_SERVER_ERROR),
NO_ACTIVE_USERS_FOR_MERCHANT("no_active_users_for_merchant", "There are not active users for merchant", HttpStatus.NOT_FOUND),
NO_ACTIVE_USER_FOR_MERCHANT("no_active_user_for_merchant", "The user is not active for merchant", HttpStatus.NOT_FOUND),
ERROR_RETRIEVING_ACTIVE_USERS_FOR_MERCHANT("error_retrieving_active_users_for_merchant", "Error retrieving active users for merchant", HttpStatus.INTERNAL_SERVER_ERROR),
UNSPECIFIED_USERS("unspecified_users", "Unspecified users", HttpStatus.BAD_REQUEST);

If the custom notification arrives without receivers, we will include a UNSPECIFIED_RECEIVERS error.

If the custom notification arrives with receivers but without users, we will add the UNSPECIFIED_USERS error with a custom description like "Unspecified users for merchant 64e5fe2e34951d5b444a511a." However, we will not throw an exception because we need to continue processing the remaining merchants.

If we encounter an issue retrieving active user IDs for a merchant, we will notify you with ERROR_RETRIEVING_ACTIVE_USERS_FOR_MERCHANT and a custom description like "Error retrieving active users for merchant 64e5fe2e34951d5b444a511a." Still, we will not throw an exception since we have to continue processing the remaining merchants.

If there are no active users for the specified merchant, we will return NO_ACTIVE_USERS_FOR_MERCHANT with a custom description like "There are no active users for merchant 64e5fe2e34951d5b444a511a." However, we will not throw an exception due to the need to continue processing the rest of the merchants.

If we have active users for the merchant, but you send a user who is not enabled or associated with the specified merchant and/or customer, we will include a NO_ACTIVE_USER_FOR_MERCHANT error for each such user, with a custom description like "The user 64e5fe2e34951d5b444a5122 is not active for merchant 64e5fe2e34951d5b444a511a."

If we encounter issues mapping the custom notification to a Toqio notification for retrieval by users from the web and app platforms, we will notify you with a UNABLE_TO_MAP_CUSTOM_NOTIFICATION error. Since the mapping is common for all notifications we deliver, we will need to throw an exception after processing all receivers.

If we experience problems saving the notification, we will notify you with a UNABLE_TO_SAVE_CUSTOM_NOTIFICATION error.

After processing all the notifications, we will attempt to notify you. If we cannot connect with you to deliver the errors, we will encounter an exception like CUSTOM_NOTIFICATION_NOT_DELIVERED, specifying the issue.

Push notifications error handling

We use the same principle for push notifications.

The possible errors you may encounter include the following. Note that the descriptions provided here may be expanded to include more detailed information, such as adding relevant IDs:

UNSPECIFIED_RECEIVERS("unspecified_receivers", "Unspecified receivers", HttpStatus.BAD_REQUEST),
CUSTOM_NOTIFICATION_NOT_DELIVERED("custom_notification_not_delivered", "Custom notification not delivered", HttpStatus.INTERNAL_SERVER_ERROR),
CUSTOM_NOTIFICATION_ERRORS_NOT_DELIVERED("custom_notification_errors_not_delivered", "Custom notification errors not delivered", HttpStatus.INTERNAL_SERVER_ERROR),
UNABLE_TO_MAP_CUSTOM_NOTIFICATION("unable_to_map_custom_notification", "Unable to map notification", HttpStatus.INTERNAL_SERVER_ERROR),
NO_ACTIVE_USERS_FOR_MERCHANT("no_active_users_for_merchant", "There are not active users for merchant", HttpStatus.NOT_FOUND),
UNSPECIFIED_USERS("unspecified_users", "Unspecified users", HttpStatus.BAD_REQUEST),
INVALID_USER_LANGUAGE_CONFIGURED("invalid_user_language_configured", "Invalid user language configured", HttpStatus.NOT_FOUND),
ERROR_PROCESSING_DATA("error_processing_data", "Error processing data", HttpStatus.BAD_REQUEST),
PUSH_NOTIFICATIONS_DISABLED("push_notifications_disabled", "Push notifications disabled", HttpStatus.FORBIDDEN);

If the custom notification arrives without receivers, we will include an UNSPECIFIED_RECEIVERS error.

If the custom notification arrives with receivers but without users, we will add the UNSPECIFIED_USERS error with a custom description like "Unspecified users for merchant 64e5fe2e34951d5b444a511a." However, we will not throw an exception, as we have to continue processing the remaining merchants.

If any user is not enabled or present, or the associated customer does not contain the integrator, we will include a NO_ACTIVE_USER_FOR_MERCHANT error for each such user with the same issue, along with a custom description like "The user 64e5fe2e34951d5b444a5122 is not active."

If we encounter an issue while mapping the custom notification to a Toqio notification that is supposed to be saved and retrieved by the user from the app platforms, we will notify them with a UNABLE_TO_MAP_CUSTOM_NOTIFICATION error. As the mapping is common for all notifications we deliver, we will need to throw an exception after processing all receivers.

If we experience a problem retrieving the user's language, we will notify you with an INVALID_USER_LANGUAGE_CONFIGURED error, accompanied by a custom description like "The user 64e5fe2e34951d5b444a5122 has an invalid language configured."

If we encounter issues processing the data section of the request, we will notify you with an ERROR_PROCESSING_DATA error.

If the user does not have configuration related to push notifications or the push notifications are disabled, we will notify you with a PUSH_NOTIFICATIONS_DISABLED error, along with a custom description like "Push notifications disabled for user %."

Once we have processed all notifications, we will attempt to notify you. If we cannot connect with you to deliver the errors, we will encounter an exception like CUSTOM_NOTIFICATION_NOT_DELIVERED, specifying the issue.