feat: detailed error elated to API key and environment mismatch

[hiohiohio]

Context:

• it is hard to understand the errors related to API key and environment mismatch
• this PR introduces detailed error message and also tips for http status code 401/403

Changes:

• add detailed error message for APIError
• add tips message for http status code 401/403 for APIError

Examples:

trading api

from alpaca.trading.client import TradingClient
from alpaca.common.exceptions import APIError

api_key=BROKER_KEY
secret_key=BROKER_SECRET
# paper = True
paper = False

trader = TradingClient(api_key, secret_key, paper=paper)
trader.get_account()

output

APIError: {'payload': '{"code":40110000,"message":"request is not authorized"}', 'status_code': 401, 'reason': 'Unauthorized', 'method': 'GET', 'url': 'https://api.alpaca.markets/v2/account', 'tips': 'please check your API key and environment (paper/sandbox/live)'}

broker api

from alpaca.broker.client import BrokerClient
api_key = BROKER_API_KEY + "1"  # to raise error
client = BrokerClient(api_key=api_key, secret_key=BROKER_API_SECRET, sandbox=True)
client.list_accounts()

output

APIError: {'payload': '{"message": "forbidden."}\n', 'status_code': 403, 'reason': 'Forbidden', 'method': 'GET', 'url': 'https://broker-api.sandbox.alpaca.markets/v1/accounts', 'tips': 'please check your API key and environment (paper/sandbox/live)'}

[hiohiohio]

sorry, please let me re-consider about compatibility with previous message field.

[umitanuki]

Do you need 403 here? If the URL is incorrect, you should check only 401?

[hiohiohio]

If I connect to live (sandbox=False) with a key for sandbox, it returns 403 as below. Therefore, it might be worth to include 403 ?

from alpaca.broker.client import BrokerClient
client = BrokerClient(api_key=BROKER_API_KEY, secret_key=BROKER_API_SECRET, sandbox=False)
client.list_accounts()

APIError: {'payload': '{"message": "forbidden."}\n', 'status_code': 403, 'reason': 'Forbidden', 'method': 'GET', 'url': 'https://broker-api.alpaca.markets/v1/accounts', 'tips': 'please check your API key and environment (paper/sandbox/live)'}

[umitanuki]

If should be one of those. 403 is sad because API returns it for other cases as well such as not enough shares to sell. Downside of this approach is that the new error could be confusing in those cases unless you are really specific to the particular api auth error case

[hiohiohio]

Understood. Thank you for the info. In that case, agree, 401 only would be nicer. User still can get a hint by url strings.

[umitanuki]

My question is, does api even return 401?

[hiohiohio]

Yes. API returns 401 when paper=False and use a key for paper as I wrote the first case in description.

[hiohiohio]

returns tips message only for 401. Addressed b7f027f