Errors

All exceptions inherit from StoneXError. See the Error handling guide for usage patterns.

stonepy.StoneXError

Bases: Exception

Base class for all stonepy errors.

stonepy.ConfigurationError

Bases: StoneXError

The client is not configured for the attempted operation.

Raised when a session-authenticated call needs a token refresh but no credentials were configured on ClientConfig and no manual log_on has succeeded.

stonepy.AuthenticationError

AuthenticationError(
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
)

Bases: StoneXAPIError

Invalid credentials (ErrorCode 4010 or 4011) or an unrecoverable HTTP 401.

Carries the same attributes as StoneXAPIError.

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
) -> None:
    self.http_status = http_status
    self.error_code = error_code
    self.error_message = error_message
    self.method = method
    self.path = path
    self.raw_body = raw_body
    self.headers = dict(headers)
    super().__init__(
        f"{method} {path} -> HTTP {http_status} (ErrorCode={error_code}): {error_message}"
    )

stonepy.RateLimitError

RateLimitError(
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
    retry_after: float | None = None,
)

Bases: StoneXAPIError

Rate-limit API error (HTTP 429) with an optional parsed retry-after delay.

Extends StoneXAPIError.

Attributes:

Name	Type	Description
retry_after		Seconds to wait before retrying, parsed from the Retry-After header when the server supplies it; otherwise None.

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
    retry_after: float | None = None,
) -> None:
    self.retry_after = retry_after
    super().__init__(
        http_status=http_status,
        error_code=error_code,
        error_message=error_message,
        method=method,
        path=path,
        raw_body=raw_body,
        headers=headers,
    )

stonepy.OrderRejectedError

OrderRejectedError(
    *,
    status: int | str,
    status_reason: int | None,
    reason: str | None,
    response: object,
    method: str | None = None,
    path: str | None = None,
    http_status: int | None = None,
)

Bases: StoneXError

Order business-status rejection with optional endpoint context.

Raised when an order endpoint returns HTTP success but a business status that means the order was rejected or blocked. response is retained for diagnostics and may contain sensitive response data; it is intentionally omitted from repr().

Attributes:

Name	Type	Description
status		The order Status code that triggered the rejection (an int code or a text status such as "Failure").
status_reason		The StatusReason code, if the response supplied one.
reason		A human-readable reason, decoded from the status/reason codes.
response		The parsed response model or mapping (may be sensitive).
method		The HTTP method of the originating request, if known.
path		The request path of the originating request, if known.
http_status		The HTTP status code of the response, if known.

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    status: int | str,
    status_reason: int | None,
    reason: str | None,
    response: object,
    method: str | None = None,
    path: str | None = None,
    http_status: int | None = None,
) -> None:
    self.status = status
    self.status_reason = status_reason
    self.reason = reason
    self.response = response
    self.method = method
    self.path = path
    self.http_status = http_status
    endpoint = f"{method} {path} -> HTTP {http_status}: " if method and path else ""
    super().__init__(f"{endpoint}Order rejected: status={status} reason={reason!r}")

stonepy.OrderStatusUnknownError

OrderStatusUnknownError(
    *,
    status: int | str,
    status_reason: int | None,
    response: object,
    method: str | None = None,
    path: str | None = None,
    http_status: int | None = None,
)

Bases: StoneXError

Indeterminate order acknowledgement with optional endpoint context.

Raised when a non-idempotent order write returns an undocumented or wrong-domain business status, so stonepy cannot determine whether the instruction succeeded. This is deliberately not an OrderRejectedError: rejection handlers must not assume the write is safe to repeat. response is retained for diagnostics and may contain sensitive response data; it is intentionally omitted from repr().

Attributes:

Name	Type	Description
status		The unrecognized status value.
status_reason		The accompanying numeric reason, if one could be read.
response		The parsed response model or mapping (may be sensitive).
method		The HTTP method of the originating request, if known.
path		The request path of the originating request, if known.
http_status		The HTTP status code of the response, if known.

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    status: int | str,
    status_reason: int | None,
    response: object,
    method: str | None = None,
    path: str | None = None,
    http_status: int | None = None,
) -> None:
    self.status = status
    self.status_reason = status_reason
    self.response = response
    self.method = method
    self.path = path
    self.http_status = http_status
    endpoint = f"{method} {path} -> HTTP {http_status}: " if method and path else ""
    super().__init__(
        f"{endpoint}Unknown order status {status!r}. The order MAY OR MAY NOT have been "
        "placed; verify order state before resubmitting."
    )

stonepy.StoneXAPIError

StoneXAPIError(
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
)

Bases: StoneXError

HTTP or API business-error response with endpoint context.

raw_body is retained for diagnostics and may contain sensitive response data. It is intentionally omitted from both str() and repr().

Attributes:

Name	Type	Description
http_status		The HTTP status code of the failing response.
error_code		The StoneX ErrorCode from the response body, if present.
error_message		The human-readable error message from the response, if present.
method		The HTTP method of the request that failed.
path		The request path that failed.
raw_body		The raw response body, retained for diagnostics (may be sensitive).
headers		The response headers. When this error is raised by the client the secret-named headers are already redacted, and repr() redacts them again.

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    http_status: int,
    error_code: int | None,
    error_message: str | None,
    method: str,
    path: str,
    raw_body: bytes | None,
    headers: Mapping[str, str],
) -> None:
    self.http_status = http_status
    self.error_code = error_code
    self.error_message = error_message
    self.method = method
    self.path = path
    self.raw_body = raw_body
    self.headers = dict(headers)
    super().__init__(
        f"{method} {path} -> HTTP {http_status} (ErrorCode={error_code}): {error_message}"
    )

stonepy.ResponseParseError

ResponseParseError(
    *,
    phase: str,
    http_status: int,
    method: str,
    path: str,
    raw_body: bytes,
    message: str,
)

Bases: StoneXError

Malformed or schema-invalid success response body.

raw_body is retained for diagnostics and may contain sensitive response data. It is intentionally omitted from str() and redacted from repr().

Attributes:

Name	Type	Description
phase		Where parsing failed - "decode" (invalid JSON) or "validate" (JSON that did not match the response model).
http_status		The HTTP status code of the response that failed to parse.
method		The HTTP method of the originating request.
path		The request path of the originating request.
raw_body		The raw response body, retained for diagnostics (may be sensitive).

Source code in src/stonepy/_core/errors.py

def __init__(
    self,
    *,
    phase: str,
    http_status: int,
    method: str,
    path: str,
    raw_body: bytes,
    message: str,
) -> None:
    self.phase = phase
    self.http_status = http_status
    self.method = method
    self.path = path
    self.raw_body = raw_body
    super().__init__(
        f"{method} {path} -> HTTP {http_status} response {phase} failed: {message}"
    )

stonepy.TransportError

TransportError(
    message: str, *, method: str, path: str, attempt: int
)

Bases: StoneXError

Network-level failure (connect, read, or timeout) after retries are exhausted.

Attributes:

Name	Type	Description
method		The HTTP method of the request that failed.
path		The request path that failed.
attempt		The zero-based retry attempt on which the failure was raised.

Source code in src/stonepy/_core/errors.py

def __init__(self, message: str, *, method: str, path: str, attempt: int) -> None:
    self.method = method
    self.path = path
    self.attempt = attempt
    super().__init__(f"{method} {path} transport failed on attempt {attempt}: {message}")