# Core

## Domain Types

### Error Data

- `ErrorData = object { kind, message, scope }`

  - `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: string`

    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 = ValidationErrorData or ErrorData`

  - `ValidationErrorData = object { fields, kind, message, 2 more }`

    - `fields: array of FieldValidationError`

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

      - `field: string`

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

      - `messages: array of string`

        One or more error messages

    - `kind: "validation"`

      General error category

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

      - `"validation"`

    - `message: string`

      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"`

  - `ErrorData = object { kind, message, scope }`

    - `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: string`

      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

- `ErrorKind = "entity_not_found" or "path_invalid" or "path_unknown" or 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)

### Error Response

- `ErrorResponse = object { data, error, status, status_text }`

  - `data: unknown`

    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

    - `ValidationErrorData = object { fields, kind, message, 2 more }`

      - `fields: array of FieldValidationError`

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

        - `field: string`

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

        - `messages: array of string`

          One or more error messages

      - `kind: "validation"`

        General error category

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

        - `"validation"`

      - `message: string`

        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"`

    - `ErrorData = object { kind, message, scope }`

      - `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: string`

        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: number`

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

  - `status_text: string`

    HTTP status text

### Error Scope

- `ErrorScope = "user" or "client" or "server"`

  - `"user"`

  - `"client"`

  - `"server"`

### Field Validation Error

- `FieldValidationError = object { field, messages }`

  - `field: string`

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

  - `messages: array of string`

    One or more error messages

### Interval

- `Interval = object { unit, value }`

  Interval period & size

  - `unit: IntervalUnit`

    - `"h"`

    - `"d"`

    - `"w"`

    - `"m"`

    - `"y"`

  - `value: number`

### Interval Unit

- `IntervalUnit = "h" or "d" or "w" or 2 more`

  - `"h"`

  - `"d"`

  - `"w"`

  - `"m"`

  - `"y"`

### Validation Error Data

- `ValidationErrorData = object { fields, kind, message, 2 more }`

  - `fields: array of FieldValidationError`

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

    - `field: string`

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

    - `messages: array of string`

      One or more error messages

  - `kind: "validation"`

    General error category

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

    - `"validation"`

  - `message: string`

    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

- `ValidationFieldSource = "header" or "query" or "path" or "body"`

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

  - `"header"`

  - `"query"`

  - `"path"`

  - `"body"`