# Shared

## Domain Types

### API Error

- `class APIError: …`

  A direct mapping of tonic::Status, for use in HTTP responses.

  - `code: int`

    The error code is used to identify the nature of the error. It corresponds
    to an HTTP status code.

  - `message: str`

    A human-readable message providing more details about the error.

  - `details: Optional[List[Dict[str, object]]]`

    Additional error details, if any. This can include structured information
    such as field violations or error metadata.

### Base Response

- `class BaseResponse: …`

  - `metadata: ResponseMetadata`

    Response metadata, including the request ID and optional pagination info.

    - `request_id: str`

      A unique ID for this request, generated upon ingestion of the request.

    - `next_page_token: Optional[str]`

      Base64URL-encoded pagination token containing limit and offset

    - `page_number: Optional[int]`

      Pagination. Included if this was a GET (list) response

    - `previous_page_token: Optional[str]`

      Base64URL-encoded pagination token containing limit and offset

    - `total_items: Optional[int]`

      Total number of items available (not just in this page).

    - `total_pages: Optional[int]`

      Total number of pages available.

  - `error: Optional[APIError]`

    Structured error details when the request is unsuccessful.

    - `code: int`

      The error code is used to identify the nature of the error. It corresponds
      to an HTTP status code.

    - `message: str`

      A human-readable message providing more details about the error.

    - `details: Optional[List[Dict[str, object]]]`

      Additional error details, if any. This can include structured information
      such as field violations or error metadata.

### Response Metadata

- `class ResponseMetadata: …`

  Metadata for the response. This will always contain a request ID which can be used to identify
  the request to Clear Street for tracing, and optionally may include pagination data.

  - `request_id: str`

    A unique ID for this request, generated upon ingestion of the request.

  - `next_page_token: Optional[str]`

    Base64URL-encoded pagination token containing limit and offset

  - `page_number: Optional[int]`

    Pagination. Included if this was a GET (list) response

  - `previous_page_token: Optional[str]`

    Base64URL-encoded pagination token containing limit and offset

  - `total_items: Optional[int]`

    Total number of items available (not just in this page).

  - `total_pages: Optional[int]`

    Total number of pages available.