Understand policy search and failure
An OPA policy defines which answers are acceptable. If an answer does not satisfy the policy, Struct searches for alternative solutions within the configured budget.
This happens within one /v1/resolve request. Your client receives a compliant answer or an error—not the intermediate rejected candidates.
What the search can achieve
Struct is a system-one model: it makes direct judgments without a long explicit reasoning trace. Policy search considers alternative answers. It is useful when the model has a reasonable idea of a solution but may miss a restriction, count or relationship on its first attempt.
It is not exhaustive search and does not guarantee the most probable answer over every possible output. If the model has little useful knowledge of a problem, the valid answer is exceptionally hard to discover, or the rules conflict, search can fail. More retries do not fix a lack of information or make an impossible task possible.
Set a budget
Attach a policy or registered policy_id, then optionally set policy_max_retries:
| Value | Behavior |
|---|---|
0 | No retry after the initial attempt. |
8 | At most eight retries after the initial attempt. |
| Omitted | Defaults to 32 when a policy is attached. |
The accepted range is 0–128. Service execution limits still apply. Increasing the budget allows more work and can increase latency; it does not guarantee success. Requests without policies do not run policy search.
Help the model find an answer
Use clear descriptions to explain the intended output, the evidence to use and the important constraints. Keep those instructions consistent with Rego. Supply relevant state when a valid answer depends on facts outside the user's message.
A policy can provide feedback explaining why an answer failed. policy_feedback: "chat" uses that guidance to help Struct find an alternative that satisfies the requirements. inline is another supported mode; off disables feedback guidance. Feedback mode is separate from the retry budget.
The exact text example provides a complete feedback_entrypoint rule. It names the affected field and explains the count still needed. Only include information the model may see in feedback; diagnostic messages can reveal otherwise private policy data.
Handle success and failure
On success, read output. Successful policy metadata includes status: "allow". A result can be compliant while still misinterpreting facts that the policy does not check.
If the search budget ends without a compliant answer, the service returns HTTP 422 with code POLICY_SEARCH_EXHAUSTED. There is no generated answer to consume. Distinguish this from malformed requests, unsupported policies and capacity errors using the error reference.
A search failure does not prove no solution exists. It says this request did not find one within the available budget. Your application might ask for missing information, return a controlled failure, or send the task for review.
An explicit fallback is different
You can include a review or unknown value in the schema and permit it in the policy. The model may then produce that as a valid answer. It is not the same as search exhaustion: Struct does not add a fallback field or weaken your rules automatically.
Permission context demonstrates a permitted review outcome. OPA basics includes a complete request without any fallback value.