Callback error handling

Callbacks can define their own error responses, but the Acronis API Callback Gateway provides default handling for specific HTTP error response codes and communication errors.

UI error message template

Error messages, that are displayed in the user interface, are constructed using the following template:

Could not establish connection to <CyberApp name> CyberApp. <human readable error message>. Please contact <company name> support (<contacts>).

Placeholder	Description	Source
<CyberApp name>	The official name of the CyberApp	CyberApp Description > About CyberApp > Name
<company name>	Company name from support contact	CyberApp Description > Support contact > Company name
<contacts>	Contact information (comma-separated)	CyberApp Description > Support contact > Website, Email, Phone (only non-empty values)
<human readable error message>	See the human-readable error messages in “Default error response codes” and “Communication errors”

Default error response codes

These HTTP status codes do not need to be specified in callbacks. The Acronis API Callback Gateway will process them.

A corresponding error message will also be rendered in the user interface for partners and customers.

Status code	Reason	Human-readable error message
401 Unauthorized	The callback handler rejected the unauthorized request.	The vendor cloud returned authentication failed (401).
403 Forbidden	The callback handler rejected the request due to invalid credentials.	The vendor cloud refused authorization (403).
410 Gone	The callback handler is no longer available at the provided URL.	Invalid response schema from the vendor cloud.
429 Too Many Requests	The callback handler rejected the request due to too many requests. The request can be retried by API Callback Gateway.	The vendor cloud returned an unexpected error code 4XX.
500-599	The callback handler responded with an error that indicates a server error.	The vendor cloud returned an unexpected error code 5XX.

Enablement error messages

A callback handler can include a human-readable error message in the err_message field of the response body. An error message may indicate a precondition that must be met before enabling the CyberApp for a partner or customer. For example, a Managed Security Service Provider (MSSP) may need to sign a contract before enabling the CyberApp for their customers and return an appropriate error message that will appear as follows:

This message can be displayed in the user interface when attempting to enable the CyberApp in the following scenarios:

• Mapping the partner ID to the Acronis tenant ID

• Writing the customer mapping to your service

• Enabling a partner using mirroring

• Enabling customers using mirroring

Communication errors

The following communication errors will be handled by the Acronis API Callback Gateway.

A corresponding error message will be rendered in the user interface for MSPs and customers.

Error	Reason	Human-readable error message
TLS handshake failed	Acronis API Callback Gateway was unable to negotiate the secure protocol with the callback handler.	SSL Handshake with the vendor cloud failed.
Invalid SSL certificate	Acronis API Callback Gateway was unable to verify the SSL certificate of the callback handler domain name.	Failed to validate the vendor cloud SSL certificates.
Server is unreachable	Acronis API Callback Gateway was unable to find a route to the callback handler. The request can be retried by API Callback Gateway.	The vendor cloud is unreachable.
Connection timed out	Acronis API Callback Gateway was able to establish the connection but did not receive a response within the specific time. The request can be retried by API Callback Gateway.	Timed out contacting the vendor cloud (522/524).
Unexpected 2xx-3xx response	Callback handler responded with a response within the 200-399 range that does not match any code defined for this callback.	The vendor cloud returned an unexpected error code 2XX-3XX.
Unexpected 4xx response	Callback handler responded with a response within the 400-499 range that does not match any code defined for this callback or in the Status codes table.	The vendor cloud returned an unexpected error code 4XX.
Response schema error	Callback handler responded with a structure that does not match the schema defined for this callback.	Invalid response schema from the vendor cloud.
Request schema error	Callback handler received a request from the user interface which structure does not match the schema defined for this callback.	Acronis internal error. Please contact support.