When calling POST /v1/reason, you may encounter answers where grounding.used: 0 accompanied by the X-Dike-Grounding: weak response header, or an explicit refusal sentinel.

1. Filter Over-Constraining

The most common cause of false-negative grounding is applying filters that unintentionally exclude the governing statute.

Common Pitfalls

• status: ["in_force"]: If the legal query relates to a transaction executed under an older law or asks about a repealed code, filtering to in_force will exclude the relevant historical articles from retrieval.
• jurisdiction Mismatch: Querying Saudi legal concepts with jurisdiction: "EG" will return zero relevant candidates.
• Narrow doc_type: Restricting doc_type: ["legislation"] when the authoritative rule is established by a Court of Cassation principle (case_law).

2. Query Breadth vs. top_k Capacity

The default top_k: 12 budget retrieves approximately 12 legal chunks into the reasoning prompt.

• If a query spans multiple complex legal domains (e.g. قارن بين مسؤولية المقاول ومسؤولية المهندس المعماري في عقود الفيدك والقانون المدني), 12 chunks may not cover all required articles.
• Remediation: Increase top_k to 20 or 25, or split the question into focused sub-inquiries.

3. Genuine Statutory Gaps

Certain specialized legal areas or historical case law years may not yet be indexed in Dike's public corpus.

• Compare against the Jurisdictions & Coverage matrix.
• If the law is missing, contact support to submit an indexing request.

4. UI Handling Best Practice

In user-facing applications, inspect X-Dike-Grounding: weak and render an informative warning card:

{isWeakGrounding && (
  <div className="rounded-lg border border-amber-200 bg-amber-50 p-3 text-sm text-amber-800">
    <p className="font-medium">تنبيه قانوني:</p>
    <p>لم يتم العثور على نصوص قانونية قاطعة في قاعدة البيانات لدعم هذه الإجابة بشكل كامل. يرجى مراجعة محامٍ مختص.</p>
  </div>
)}

Next Steps

• Explore MCP Debugging.
• Check the Frequently Asked Questions.