Error Handling

This section provides an overview of common errors in the XAP API and recommended solutions.

Overview

When integrating the XAP API, your application should include error-handling logic to manage issues that may arise when making requests to API endpoints.

You should be prepared to handle two main types of errors:

• Network Connection Failures: These occur when the client is unable to establish a connection to the endpoint before receiving a response. Causes may include routing issues, service disruptions, or timeouts along the network path.

• HTTP Errors: These occur when the endpoint responds with a client error (4xx) or server error (5xx). The response body may contain detailed information about the error.

This page include common error codes and solutions suggested. For detailed error code and error details, please refer to Error codes from each API page.

Network Connection Failures

If a network connection failure occurs before the client receives a response, the request state is uncertain. The request may have been successfully completed but failed before reaching the client, failed while being processed by the server, or not reached the endpoint at all.

Typically, if our service is unavailable for any reason, a 503 - Service Unavailable error is returned.

Recommended Actions

We recommend limiting the number of request and using a retry mechanism.

If the issue persists after reaching the retry limit, contact us for assistance.

HTTP Status Codes

• 2xx: These codes indicate a successful request and that the server processed it as expected.

• 4xx: These indicate client errors, meaning the request cannot be fulfilled due to incorrect information or missing parameters (e.g., missing required parameters, upload failures, etc.).

• 5xx: These indicate server errors.

Common Error Codes

400 - Bad Request

The request URL or body format is incorrect, or invalid data is included. Example:

{
    "TransactionId": "50e6b4dd-9e7c-42d1-9e0c-f37d6f7a103c",
    "Errors": [
        {
            "Code": "INVALID_CLIENT_KEY",
            "Description": "Invalid client key: null."
        }
    ]
}

✅ Solution: Check the request format, parameter values, and ensure all required parameters are included.

At the above example, it is missing the required Header.

401 - Unauthorized

Access is denied due to invalid authentication credentials.

✅ Solution: Verify your authentication credentials and ensure the correct Authentication are provided.

403 - Forbidden

Authentication was successful, but the user does not have permission to access the requested resource.

✅ Solution: Check your permission settings and ensure the API key has the appropriate access rights for the requested resource.

404 - Not Found

The requested resource does not exist.

✅ Solution: Verify the requested URL and ensure the path is correct and the resource exists.

429 - Too Many Requests

The server has denied the request due to rate limits being exceeded.

✅ Solution:

• Limit the number of requests, and increase wait times between retries.
• If you need higher API call quotas, please contact us to learn more about the requirements for upgraded quotas.

500 - Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

✅ Solution: Retry the request later. If the issue persists, contact support if needed.

503 - Service Unavailable

The server is temporarily unable to handle the request, usually due to overload or maintenance.

✅ Solution:

• Retry the request after an appropriate delay.
• Ensure compliance with API rate limits to avoid overloading the server.

504 - Gateway Timeout

The server, acting as a gateway or proxy, did not receive a timely response from an upstream server.

✅ Solution:

• Retry the request after a reasonable time.
• Check for network stability issues.
• If the issue persists, contact our technical support.