# 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:

```json
{
  "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. |