Skip to main content

​
Decision gives an unexpected result

Symptoms: aethis_decide returns not_eligible when you expect eligible, or vice versa. Steps:
  1. Call aethis_explain (or aethis explain -b <ruleset_id> in the CLI) to see human-readable descriptions of the compiled rules. Check that the rules match your source text.
  2. Call aethis_decide with include_trace: true. The trace shows exactly which criterion failed and why.
  3. If the rules are wrong, add a guidance hint pointing to the specific clause that was missed, then aethis_refine.
aethis_decide({
  ruleset_id: "my_section:20260416-abc123",
  field_values: { ... },
  include_trace: true,
  include_explanation: true
})

​
Undetermined outcome

What it means: The engine received the input fields but could not reach a definitive decision — the case falls outside the compiled rules or a required field was not provided. When to expect it:
  • A required field was missing from field_values
  • The source legislation has a discretionary clause (“may be granted”, “at the authority’s discretion”) — Aethis compiles these as undetermined rather than guessing
  • The case involves a combination of values not covered by any rule
How to handle it in your application:
  • undetermined means flag for human review, not auto-reject
  • Check fields_evaluated vs fields_provided — if they differ, a field was unrecognised or missing
  • Use aethis_next_question to find out what additional information the engine needs

​
Updating rules after publishing

Published rulesets are locked — this is intentional. To update:
  1. aethis_generate_and_test on the same project (adds a new ruleset version)
  2. Refine with aethis_refine until all tests pass
  3. aethis_publish — auto-deprecates the previous active ruleset
The old ruleset remains accessible by its specific ruleset ID. Systems pointing to latest_active automatically use the new version.

​
Generation timeout (504)

Don’t re-trigger — the server keeps running after your client disconnects. See Handling generation timeouts for the recovery flow.

​
DATE field type error

Date fields take an ISO "YYYY-MM-DD" string or an integer ordinal on ruleset evaluations (ISO accepted since engine 0.31.0); rulebook evaluations still require ordinals. Details and conversion snippet: Date field values.

​
”API key is required” on decision tools

Decision tools (aethis_decide, aethis_schema, aethis_next_question, aethis_explain) require no API key. If you see this error on a decision tool:
  • Check that you’re calling a decision tool, not an authoring tool
  • Make sure AETHIS_API_KEY is not set to an invalid value (empty string counts)

​
“Ruleset not found” (404)

  • Verify the ruleset ID format: section_id:YYYYMMDD-xxxxxxxx
  • Call aethis_list_projects → aethis_list_rulesets to find valid IDs
  • Check the ruleset hasn’t been archived

​
”Cannot publish: tests failing”

All tests must pass before publishing. Options:
  • Fix rules with aethis_refine and feedback pointing to the missed clause
  • Use aethis_explain_failure to get a targeted diagnosis for a specific failing case
  • Pass force: true to publish anyway (not recommended for production)

​
Rate limit exceeded (429)

{
  "error": "rate_limit_exceeded",
  "retry_after": 1714000000
}
Wait until the X-RateLimit-Reset timestamp, then retry. Contact eng@aethis.ai to increase your tier.
Help improve this pageIf something here is unclear or missing an example, use the feedback button at the bottom of the page.Found a bug? Open a GitHub issue. Evaluating Aethis for a regulated workflow? Contact us directly.