Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/markzuckerbergas/gbmplus-api-python/llms.txt

Use this file to discover all available pages before exploring further.

The GBM Plus SDK raises typed exceptions from gbmplus.exceptions so you can handle specific failure modes precisely in your code. Instead of catching a generic Exception, you can target exactly what went wrong — missing credentials, a failed login, an HTTP error from the API, or a malformed order — and respond accordingly.
All SDK exceptions inherit directly from Python’s built-in Exception class, so they are fully compatible with standard try/except patterns and third-party error-tracking libraries.

​
Exception types

ExceptionWhen it is raised
UserErrorAt instantiation, when one or more of user_email, user_password, or client_id is missing (not passed and not set as an environment variable).
AuthenticationErrorWhen the SDK successfully sends credentials to the GBM+ auth endpoint but the server rejects them — wrong email, password, or client ID.
APIErrorOn any HTTP error response from the GBM+ API (4XX or 5XX) after all retry attempts have been exhausted. Carries structured metadata about the failure.
OrderFormatErrorWhen generateOrderObject is called with trading_type=TradingTypes.Limited but no price argument is provided.

​
APIError attributes

APIError exposes the following attributes for programmatic inspection:
AttributeTypeDescription
statusint | NoneHTTP status code returned by the API (e.g. 404, 500).
reasonstr | NoneHTTP reason phrase (e.g. "Not Found", "Internal Server Error").
messagedict | str | NoneParsed JSON body of the response, or the first 100 bytes of the raw content if the body is not valid JSON.
tagstrAPI section tag identifying the endpoint group (e.g. "accounts", "orders").
operationstrName of the operation that failed (e.g. "getAccounts", "placeOrder").

​
Importing exceptions

Import the exceptions you need directly from gbmplus.exceptions: 
from gbmplus.exceptions import UserError, AuthenticationError, APIError, OrderFormatError

​
Handling credential and auth errors

Credential and authentication errors are raised during GBMPlusAPI() construction — before any API call is made. Wrap the instantiation in a try/except block to handle them gracefully: 
import gbmplus
from gbmplus.exceptions import UserError, AuthenticationError

try:
    gbm = gbmplus.GBMPlusAPI()
except UserError as e:
    print("Missing credentials:", e)
    # e.message -> "User email, password and client_id need to be defined"
except AuthenticationError as e:
    print("Authentication failed:", e)
    # e.message -> "There was an authentication error. Verify that email, password and client_id are correct"
UserError is raised when any of the three credential fields is absent entirely. If credentials are present but incorrect (wrong password, revoked client ID), the SDK will attempt to authenticate and raise AuthenticationError instead.

​
Handling API errors

After a successful login, API calls can still fail due to network problems, invalid parameters, or server-side issues. Inspect the APIError attributes to understand exactly what went wrong: 
from gbmplus.exceptions import APIError

try:
    accounts = gbm.accounts.getAccounts()
except APIError as e:
    print(f"API error: {e.status} {e.reason}")
    print(f"Operation: {e.tag} / {e.operation}")
    print(f"Response: {e.message}")
Example output for a 404 response: 
API error: 404 Not Found
Operation: accounts / getAccounts
Response: 404 Not Found

​
Handling order format errors

OrderFormatError is raised before any network call is made, when the SDK detects that your order parameters are logically inconsistent. The most common case is using TradingTypes.Limited without supplying a price: 
import gbmplus
from gbmplus.exceptions import OrderFormatError

try:
    order = gbm.orders.generateOrderObject(
        legacy_contract_id=contract_id,
        issuer="AMZN",
        quantity=1,
        order_type=gbmplus.OrderTypes.Buy,
        trading_type=gbmplus.TradingTypes.Limited,  # requires price!
        instrument_type=gbmplus.InstrumentTypes.SIC
        # price omitted — will raise OrderFormatError
    )
except OrderFormatError as e:
    print("Order error:", e)
    # e.message -> "There was a formatting error in the order. ..."

​
Retry behaviour

The SDK has built-in automatic retry logic to handle transient failures without requiring any extra code from you.
1

5XX server errors

When the GBM+ API returns a 5XX status code, the SDK waits 1 second and retries the request automatically. This happens up to maximum_retries times (default: 2). If all retries are exhausted, APIError is raised.
2

Network exceptions

If a low-level requests.exceptions.RequestException is raised (connection reset, DNS failure, etc.), the SDK applies the same 1-second wait and retry logic as for 5XX errors.
3

4XX client errors

By default, 4XX errors are not retried — APIError is raised immediately. Set retry_4xx_error=True at instantiation to enable retries for these responses. The wait time before each retry is a random value between 1 and retry_4xx_error_wait_time seconds (default: 60).
For full details on configuring retry parameters, see the Configuration guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us