Error Codes

This page provides a comprehensive reference of error codes returned by the Webull OpenAPI.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error_code": "ERROR_CODE",
  "message": "A human-readable description of the error."
}

---

Error Code Reference

HTTP Status	error_code	Message	Description
401	MISSING_APP_KEY	Header x-app-key is missing.	The required x-app-key header was not included in the request.
401	MISSING_SIGNATURE	Header x-signature is missing.	The required x-signature header was not included in the request.
401	MISSING_ALGORITHM	Header x-signature-algorithm is missing.	The required x-signature-algorithm header was not included in the request.
401	MISSING_NONCE	Header x-signature-nonce is missing.	The required x-signature-nonce header was not included in the request.
401	MISSING_TIMESTAMP	Header x-timestamp is missing.	The required x-timestamp header was not included in the request.
401	INVALID_TOKEN	Header x-access-token is missing or invalid.	The x-access-token header is missing or contains an invalid value.
401	UNAUTHORIZED	Invalid credentials. Please verify your credentials and ensure you are connecting to the correct environment.	The app_key/app_secret is invalid, expired, revoked, disabled, or being used against the wrong environment.
401	UNAUTHORIZED	Header x-signature is invalid.	The request signature does not match the expected value. Verify your signing logic.
401	UNAUTHORIZED	Access denied. The request IP does not match your configured settings.	The source IP address is not in the configured IP whitelist.
401	UNAUTHORIZED	Access denied. Please contact support for more details.	An internal error occurred while validating IP whitelist configuration.
401	UNAUTHORIZED	Your app key has been disabled. Please contact support for more details.	Your app key has been disabled by an administrator.
401	UNAUTHORIZED	Your authorization has been revoked. Please contact your administrator.	The developer authorization has been revoked.
401	UNAUTHORIZED	Your app key is not in a valid status. Please contact support for more details.	Your app key is in an invalid state (not activated, suspended, etc.).
401	ILLEGAL_TIMESTAMP	Header x-timestamp is invalid.	The x-timestamp value is not in the expected ISO 8601 format or outside the acceptable time window.
401	VERSION_NOT_SUPPORTED	Header x-signature-version is invalid.	The x-signature-version is not supported. Currently only 1.0 is supported.
401	SIGNATURE_ALGORITHM_NOT_SUPPORTED	Header x-signature-algorithm is invalid.	The signing algorithm is not supported. Use HMAC-SHA1.
401	ROUTE_NOT_PERMITTED	You do not have permission to access this endpoint. Please contact support to request access.	Your application does not have permission to call this API endpoint.
401	UNAUTHORIZED_STREAM_DATA	Insufficient permission. Please subscribe to the required market data and try again.	Your application has not subscribed to the required market data feed. OpenAPI market data subscriptions are independent from Webull app subscriptions.
403	ACCOUNT_ACCESS_DENIED	Invalid account or insufficient permissions.	The account_id does not belong to the authenticated credentials, or there is an account_id mismatch between URL parameters and headers.
403	ROUTE_NOT_PERMITTED	You do not have permission to access this endpoint. Please contact support to request access.	Your application does not have permission to call this API endpoint.
403	MARKET_DATA_NOT_SUBSCRIBED	Insufficient permission. Please subscribe to the required market data and try again.	Market data subscription is required.
403	APP_NOT_ACTIVATED	Your app is not activated. Please contact support for more details.	Your application has not been activated.
500	SYSTEM_ERROR	An unexpected error occurred. Please try again later or contact support for more details.	An internal server error occurred. Retry with exponential backoff or contact support.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred. Please try again later or contact support for more details.	A transient internal error. Retry or contact support if the issue persists.