# Core

## Domain Types

### Error Data

- `class ErrorData: …`

  - `kind: ErrorKind`

    General error category

    Useful to match against for clients that require custom logic depending on the type of error encountered

    - `"entity_not_found"`

      Route matched, but the requested entity does not exist or could not be found

    - `"path_invalid"`

      Invalid path parameter

    - `"path_unknown"`

      Path 404s for accept json responses

    - `"path_parameter_invalid"`

      Invalid path parameter

    - `"query_invalid"`

      Invalid query parameter

    - `"query_parameter_invalid"`

      Query parameter was invalid (incorrect type, unknown enum value, etc)

    - `"query_parameter_unknown"`

      Unrecognized query parameter

    - `"query_parameter_missing"`

      A required query Parameter was not included or was empty

    - `"json_invalid"`

      Invalid json body

    - `"json_decode"`

      JSON body decode

    - `"json_body_deserialize_failure"`

      JSON body deserialization

    - `"content_type_unsupported"`

      Invalid Accept header in request

    - `"internal"`

      Internal API server errors (5xx)

  - `message: str`

    Error description

  - `scope: ErrorScope`

    The scope/region of the error.

    Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

    - `"user"`

    - `"client"`

    - `"server"`

### Error Data Variants

- `ErrorDataVariants`

  - `class ValidationErrorData: …`

    - `fields: List[FieldValidationError]`

      Field names/paths that failed validation and their associated error messages

      - `field: str`

        The name of the field which caused the error(s).

      - `messages: List[str]`

        One or more error messages

    - `kind: Literal["validation"]`

      General error category

      Useful to match against for clients that require custom logic depending on the type of error encountered

      - `"validation"`

    - `message: str`

      Error description

    - `origin: ValidationFieldSource`

      The region of the request where the validation failure(s) occurred

      - `"header"`

      - `"query"`

      - `"path"`

      - `"body"`

    - `scope: ErrorScope`

      The scope/region of the error.

      Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

      - `"user"`

      - `"client"`

      - `"server"`

  - `class ErrorData: …`

    - `kind: ErrorKind`

      General error category

      Useful to match against for clients that require custom logic depending on the type of error encountered

      - `"entity_not_found"`

        Route matched, but the requested entity does not exist or could not be found

      - `"path_invalid"`

        Invalid path parameter

      - `"path_unknown"`

        Path 404s for accept json responses

      - `"path_parameter_invalid"`

        Invalid path parameter

      - `"query_invalid"`

        Invalid query parameter

      - `"query_parameter_invalid"`

        Query parameter was invalid (incorrect type, unknown enum value, etc)

      - `"query_parameter_unknown"`

        Unrecognized query parameter

      - `"query_parameter_missing"`

        A required query Parameter was not included or was empty

      - `"json_invalid"`

        Invalid json body

      - `"json_decode"`

        JSON body decode

      - `"json_body_deserialize_failure"`

        JSON body deserialization

      - `"content_type_unsupported"`

        Invalid Accept header in request

      - `"internal"`

        Internal API server errors (5xx)

    - `message: str`

      Error description

    - `scope: ErrorScope`

      The scope/region of the error.

      Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

### Error Kind

- `Literal["entity_not_found", "path_invalid", "path_unknown", 10 more]`

  - `entity_not_found` - Route matched, but the requested entity does not exist or could not be found
  - `path_invalid` - Invalid path parameter
  - `path_unknown` - Path 404s for accept json responses
  - `path_parameter_invalid` - Invalid path parameter
  - `query_invalid` - Invalid query parameter
  - `query_parameter_invalid` - Query parameter was invalid (incorrect type, unknown enum value, etc)
  - `query_parameter_unknown` - Unrecognized query parameter
  - `query_parameter_missing` - A required query Parameter was not included or was empty
  - `json_invalid` - Invalid json body
  - `json_decode` - JSON body decode
  - `json_body_deserialize_failure` - JSON body deserialization
  - `content_type_unsupported` - Invalid Accept header in request
  - `internal` - Internal API server errors (5xx)

  - `"entity_not_found"`

    Route matched, but the requested entity does not exist or could not be found

  - `"path_invalid"`

    Invalid path parameter

  - `"path_unknown"`

    Path 404s for accept json responses

  - `"path_parameter_invalid"`

    Invalid path parameter

  - `"query_invalid"`

    Invalid query parameter

  - `"query_parameter_invalid"`

    Query parameter was invalid (incorrect type, unknown enum value, etc)

  - `"query_parameter_unknown"`

    Unrecognized query parameter

  - `"query_parameter_missing"`

    A required query Parameter was not included or was empty

  - `"json_invalid"`

    Invalid json body

  - `"json_decode"`

    JSON body decode

  - `"json_body_deserialize_failure"`

    JSON body deserialization

  - `"content_type_unsupported"`

    Invalid Accept header in request

  - `"internal"`

    Internal API server errors (5xx)

### Error Response

- `class ErrorResponse: …`

  - `data: None`

    While the `data` key does still exist in error responses, it is guaranteed to be `null`.

  - `error: ErrorDataVariants`

    Error information. Always set for unsuccessful responses

    - `class ValidationErrorData: …`

      - `fields: List[FieldValidationError]`

        Field names/paths that failed validation and their associated error messages

        - `field: str`

          The name of the field which caused the error(s).

        - `messages: List[str]`

          One or more error messages

      - `kind: Literal["validation"]`

        General error category

        Useful to match against for clients that require custom logic depending on the type of error encountered

        - `"validation"`

      - `message: str`

        Error description

      - `origin: ValidationFieldSource`

        The region of the request where the validation failure(s) occurred

        - `"header"`

        - `"query"`

        - `"path"`

        - `"body"`

      - `scope: ErrorScope`

        The scope/region of the error.

        Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

        - `"user"`

        - `"client"`

        - `"server"`

    - `class ErrorData: …`

      - `kind: ErrorKind`

        General error category

        Useful to match against for clients that require custom logic depending on the type of error encountered

        - `"entity_not_found"`

          Route matched, but the requested entity does not exist or could not be found

        - `"path_invalid"`

          Invalid path parameter

        - `"path_unknown"`

          Path 404s for accept json responses

        - `"path_parameter_invalid"`

          Invalid path parameter

        - `"query_invalid"`

          Invalid query parameter

        - `"query_parameter_invalid"`

          Query parameter was invalid (incorrect type, unknown enum value, etc)

        - `"query_parameter_unknown"`

          Unrecognized query parameter

        - `"query_parameter_missing"`

          A required query Parameter was not included or was empty

        - `"json_invalid"`

          Invalid json body

        - `"json_decode"`

          JSON body decode

        - `"json_body_deserialize_failure"`

          JSON body deserialization

        - `"content_type_unsupported"`

          Invalid Accept header in request

        - `"internal"`

          Internal API server errors (5xx)

      - `message: str`

        Error description

      - `scope: ErrorScope`

        The scope/region of the error.

        Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

  - `status: int`

    HTTP status. Successful responses are guaranteed to be < `400`.
    Conversely, error responses are guaranteed to be >= `400`.

  - `status_text: str`

    HTTP status text

### Error Scope

- `Literal["user", "client", "server"]`

  - `"user"`

  - `"client"`

  - `"server"`

### Field Validation Error

- `class FieldValidationError: …`

  - `field: str`

    The name of the field which caused the error(s).

  - `messages: List[str]`

    One or more error messages

### Interval

- `class Interval: …`

  Interval period & size

  - `unit: IntervalUnit`

    - `"h"`

    - `"d"`

    - `"w"`

    - `"m"`

    - `"y"`

  - `value: int`

### Interval Unit

- `Literal["h", "d", "w", 2 more]`

  - `"h"`

  - `"d"`

  - `"w"`

  - `"m"`

  - `"y"`

### Validation Error Data

- `class ValidationErrorData: …`

  - `fields: List[FieldValidationError]`

    Field names/paths that failed validation and their associated error messages

    - `field: str`

      The name of the field which caused the error(s).

    - `messages: List[str]`

      One or more error messages

  - `kind: Literal["validation"]`

    General error category

    Useful to match against for clients that require custom logic depending on the type of error encountered

    - `"validation"`

  - `message: str`

    Error description

  - `origin: ValidationFieldSource`

    The region of the request where the validation failure(s) occurred

    - `"header"`

    - `"query"`

    - `"path"`

    - `"body"`

  - `scope: ErrorScope`

    The scope/region of the error.

    Clients may use this to determine how to handle an error message (e.g. log it to console or display it to the user).

    - `"user"`

    - `"client"`

    - `"server"`

### Validation Field Source

- `Literal["header", "query", "path", "body"]`

  The region of the request where the validation failure(s) occurred

  - `"header"`

  - `"query"`

  - `"path"`

  - `"body"`