type: object
required:
  - error
properties:
  error:
    type: object
    required:
      - code
      - message
      - request_id
    properties:
      code:
        type: string
        enum:
          - AUTHENTICATION_ERROR
          - INVALID_REQUEST_ERROR
          - RATE_LIMIT_ERROR
          - NOT_FOUND_ERROR
          - CONFLICT_ERROR
          - INTERNAL_ERROR
        description: |
          Machine-readable error category. Use this field for programmatic
          error handling (e.g., retry on RATE_LIMIT_ERROR, re-authenticate
          on AUTHENTICATION_ERROR).
      message:
        type: string
        description: |
          Human-readable error description. Safe to display to developers
          in logs or debugging tools. Do not display to end users.
      detail:
        type: string
        description: |
          Additional context about the error, including suggestions for
          resolution. May include specific field values or limits that
          were exceeded.
      request_id:
        type: string
        format: uuid
        description: |
          Unique identifier for this request. Include this value when
          contacting Tote Developer Support for troubleshooting.
      field:
        type: ['string', 'null']
        description: |
          JSON pointer to the field that caused the error.
          Null if the error is not field-specific.
        example: "items[0].modifier_groups[1].modifiers"
      change_reasons:
        type: array
        items:
          type: string
          enum:
            - PROMO_EXPIRED
            - DISCOUNT_CHANGED
            - ITEM_PRICE_CHANGED
            - ITEM_UNAVAILABLE
            - FEE_CHANGED
        description: |
          Machine-readable reasons why the resource state changed, causing
          the conflict. Present on checkout 409 responses when expected_total
          does not match the current total. Clients should re-fetch the cart
          and call POST /carts/{cart_id}/calculate to get the updated total
          before retrying checkout.