Exception And Retry Mechanism

Abnormal

ClientException

ClientException represents an explicit client error, such as the following error codes:

Error Code	Description
SDK.SDK_INVALID_PARAMETER	An invalid parameter value was used, and an error was detected before the request was sent to the server.
SDK.SDK_ENDPOINT_RESOLVING_ERROR	Could not find a suitable Endpoint to send the request to the server
SDK.SDK_INVALID_REQUEST	A Request object is used that the framework cannot handle

ServerException

For the request result of status_code != 200, the server will provide a clear error_code as the error code during the use of the HTTP API. These failed or incorrect requests are represented by the SDK through ServerException.

For the error code and cause of ServerException, please refer to the server documentation of the HTTP API.

Retry Mechanism

Different business scenarios may require different retry policies. The SDK presets retry policies and allows custom extensions and settings.

HTTP API

Default Mechanism

1. No retry by default
2. After the number of retries is set, qualified requests will be retried, and unqualified requests will not be retried. The code example to enable retry is as follows:

Python

from webullsdkcore.client import ApiClient

# Set the maximum number of retries to 3
client = ApiClient(app_key="<your_app_key>", app_secret="<your_app_secret>", region_id="<region_id>", auto_retry=True,
                   max_retry_num=3)

Java

HttpApiConfig apiConfig = HttpApiConfig.builder()
       .appKey("<your_app_key>")
       .appSecret("<your_app_secret>")
       .regionId("<region_id>")
        // Set the maximum number of retries to 3
       .autoRetry(true)
       .maxRetryNum(3)
       .build();
TradeApiService apiService = new TradeHttpApiService(apiConfig);

The descriptions of judging default retry condition:

1. Do not retry when exceeding the maximum number of retries.
2. Do no retry when it's not a GET request.
3. Client IOError will be retried, and non-specific ClientException will not be retried.
4. The specific error code of the server (below) will be retried, and the non-specific error code will not be retried.
   • TOO_MANY_REQUESTS
   • SERVICE_NOT_AVAILABLE
   • GATEWAY_TIMEOUT
   • INTERNAL_ERROR
5. Do not retry for other errors and exceptions.

Trade Events Subscription / Quotes API

Default Mechanism

1. By default, requests that meet the conditions will be retried, and requests that do not meet the conditions will not be retried. There is no limit to the number of retries. The retry interval is 10 seconds. The code example of custom retry is as follows:

Python

from webullsdktradeeventscore.events_client import EventsClient
from webullsdkcore.retry.retry_policy import NO_RETRY_POLICY

# No Retry setting
client = EventsClient("<your_app_key>", "<your_app_secret>", region_id="<region_id>", retry_policy=NO_RETRY_POLICY)

Java

EventClient client = EventClient.builder()
        .appKey("<your_app_key>")
        .appSecret("<your_app_secret>")
        .regionId("<region_id>")
        // No Retry setting
        .reconnectBy(RetryPolicy.never())
        .build();

The default retry condition judgment description:

1. The specific error code of the gRPC protocol (as follows) is retried, and the non-specific error code is not retried.
   • 2 （UNKNOWN)
   • 13 (INTERNAL)
   • 14 (UNAVAILABLE)
2. Do not retry for other errors and exceptions.