> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Refusals

> The refusal a rater returns for a request that breaks its rules: each field, each code, the order of the checks, and the size limits.

A rater checks each request before it calculates. A request that breaks a rule gets a
**refusal** in place of a premium. The refusal lists detected violations within its size limits.
[What rslc checks and guarantees](https://docs.canary.effectiveai.app/rsl/explanation/checks-and-guarantees.md) explains why.

## The refusal

`rslc.PreparedRater.rate` returns one result for each request, the value of this JSON. This refusal comes from the rater of the
example program `effective://example-ca-ppa`, for a vehicle 60 years old in rideshare use:

```json theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
{
  "ok": false,
  "refusal": {
    "error": "BusinessRejection",
    "truncated": false,
    "violations": [
      {
        "cite": "manual:anchor \"eligibility\"",
        "code": "VEHICLE-AGE",
        "constraint": "vehicle_age: where self in [0, 45]",
        "message": "The program writes vehicles up to 45 years old.",
        "path": "Policy.vehicles[0].vehicle_age",
        "value": 60
      },
      {
        "cite": "manual:anchor \"eligibility\"",
        "code": "RIDESHARE",
        "constraint": "rideshare: where not self",
        "message": "The program doesn't cover rideshare use.",
        "path": "Policy.vehicles[0].rideshare",
        "value": true
      }
    ]
  }
}
```

> [accordion] Example invalid-input response
>
> A vehicle `use` of `"racing"` breaks only the enum rule, so the refusal is `InvalidInputs`:
>
> ```json theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> {
>   "ok": false,
>   "refusal": {
>     "error": "InvalidInputs",
>     "truncated": false,
>     "violations": [
>       {
>         "cite": null,
>         "code": "INPUT-ENUM",
>         "constraint": "use: Enum(Use)",
>         "message": "use must be one of: pleasure, commute, business, farm",
>         "path": "Policy.vehicles[0].use",
>         "value": "racing"
>       }
>     ]
>   }
> }
> ```

> [accordion] Example follow-up response
>
> The shared renters example asks `dog_has_bitten` only of a household that has a dog:
>
> ```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> has_dog: Bool [ask: "Do you have a dog?", group: "Household"],
> dog_has_bitten: Bool when self.has_dog [ask: "Has the dog bitten anyone?", group: "Household"]
> ```
>
> A request with `has_dog` as `true` that leaves out `dog_has_bitten` breaks the follow-up rule:
>
> ```json theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> {
>   "ok": false,
>   "refusal": {
>     "error": "InvalidInputs",
>     "truncated": false,
>     "violations": [
>       {
>         "cite": null,
>         "code": "INPUT-FOLLOW-UP",
>         "constraint": "Policy.dog_has_bitten when self.has_dog",
>         "message": "missing `Policy.dog_has_bitten`: it is asked when self.has_dog",
>         "path": "Policy.dog_has_bitten",
>         "value": {
>           "dog_has_bitten": null,
>           "has_dog": true
>         }
>       }
>     ]
>   }
> }
> ```

[Results](https://docs.canary.effectiveai.app/rsl/reference/results.md) describes the result that holds a refusal, for `rate` and for `evaluate`.

| Field | Value |
| - | - |
| `ok` | `false` for a refusal; `true`, with `outputs`, for a premium |
| `error` | `BusinessRejection` when any broken rule comes from the filing, with a code |
| `error` | `InvalidInputs` when every broken rule is a type, range or shape rule |
| `truncated` | `true` when the size limits below cut the list |
| `violations` | each broken rule, in the order of the checks |

Each violation has six fields:

| Field | Value |
| - | - |
| `code` | the rule's own code, or one of the `INPUT` codes below |
| `message` | the rule's own message, or a standard message |
| `path` | where the value sits in the request, such as `Policy.vehicles[0].use`; for a record rule, the record |
| `value` | the value sent; for a rule that reads several inputs, an object of them |
| `constraint` | the declaration that the value broke |
| `cite` | the rule's citation, such as `manual:anchor "eligibility"`, or `null` |

The JSON is compact, with sorted keys and numbers in exact decimal form.

## Codes

A rule with its own code reports that code. Every other rule reports one of these:

| Code | The request |
| - | - |
| `INPUT-TYPE` | sends a value of the wrong kind, leaves out a required input, or adds an unknown one |
| `INPUT-VARIANT` | names an unknown kind of record, or mixes the fields of two kinds |
| `INPUT-ENUM` | sends a value outside the enum, or outside a set such as `{6, 12}` |
| `INPUT-PATTERN` | sends a code that fails its pattern |
| `INPUT-PRECISION` | sends a number off its precision, such as 10.005 for cents |
| `INPUT-KEY` | repeats a key in a `keyed by` list |
| `INPUT-REF` | refers to a list element that is missing |
| `INPUT-RANGE` | sends a number outside its range |
| `INPUT-LEN` | sends a list that is too short or too long |
| `INPUT-UNIQUE` | repeats a value that a rule says is unique |
| `INPUT-KEY-UNFILED` | sends a `Key(T)` value that names a row missing from table `T` |
| `INPUT-FOLLOW-UP` | leaves out a follow-up input whose `when` condition holds |
| `INPUT-REQUIRES` | breaks a `requires` rule, the record rule of a rater written before RSL 0.4 |
| `INPUT-REFINEMENT` | breaks any other rule |

A rule's own code replaces the `INPUT` code of a range, length or other rule. Type checks,
`INPUT-KEY` and `INPUT-REF` keep their own codes.

## Order of the checks

The rater checks a request in three passes:

1. **Shape.** Each record, input and value has the declared kind, enum member, pattern and precision.
2. **Keys.** Each `keyed by` key is unique, and each reference names an element of its list.
3. **Rules.** Each `where` rule holds. The rater checks each record's inputs in order, then the records inside it, then the record's own rules.

Record rules that read calculated values run after ordinary input validation and before final rating outcomes.
The check for a missing follow-up input is a rule of its record, so it runs in the third pass.

One input reports at most one broken rule. A rule runs only when every value it reads passed the
earlier passes. So each violation points to its own cause.

## Size limits

| Limit | Value |
| - | - |
| Violations in one refusal | 256 |
| Size of one refusal | 60,000 bytes |
| Length of `code`, `message`, `path`, `constraint`, `cite` | 512 characters |
| Length of one text in `value` | 128 characters |
| Parts of one `value` | 32 |
| Items in one list or object of `value` | 32 |
| Depth of `value` | 8 levels |
| Records in one request | 4,096 |
| Depth of the request JSON | 128 levels |

A text cut short ends with `…`. When a limit cuts the refusal, `truncated` is `true`.

## Runtime representations

| Host | Premium | `InvalidInputs` | `BusinessRejection` |
| - | - | - | - |
| `rslc.PreparedRater.rate` | `ok: true`, `outputs` | `ok: false`, `refusal` | `ok: false`, `refusal` |
| `rslc.PreparedRater.evaluate` | `settled`, `ok: true` | `invalid` | `settled`, `ok: false` when each violation has its own code; otherwise `invalid` |
| Relativities | status `succeeded` | status `invalid_inputs` | status `refused` |

Relativities reports one violation of a refusal in the columns `reason_code` and `reason`.
For `refused` it is the first violation with a rule's own code, and for `invalid_inputs` it is the first violation.

| Column | Value |
| - | - |
| `reason_code` | the violation's `code` |
| `reason` | the violation's `path` after the root record, then a colon and the `message` |

| Rule on | `path` | `reason` |
| - | - | - |
| An input | `Policy.vehicles[0].vehicle_age` | `vehicles[0].vehicle_age: The program writes vehicles up to 45 years old.` |
| A record inside the root | `Policy.vehicles[0]` | `vehicles[0]:` and the message |
| The root record | `Policy` | the message alone |

[Results](https://docs.canary.effectiveai.app/rsl/reference/results.md) lists each field of these results, and the result for a fault.

## Related

* [RSL at a glance](https://docs.canary.effectiveai.app/rsl/language-tour.md) shows how to write each rule.
* [Rate with missing answers](https://docs.canary.effectiveai.app/rsl/how-to/rate-with-missing-answers.md) reads a refusal for a partial request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.