On this page
01
Anatomy of a block
A blocked request returns a JSON body with a readable message, a reason code, and the list of rules it broke. Some responses add details, such as the size you sent and the limit that applies.
{
"error": "Your AI request was blocked because the estimated input (18200 tokens) exceeds the active Cloptima policy limit (8000 tokens).",
"reason": "max_input_tokens_exceeded",
"violations": ["max_input_tokens_exceeded"],
"details": { "estimated_input_tokens": 18200, "max_input_tokens": 8000 }
}| Field | What it holds |
|---|---|
| error | A sentence you can show to a developer |
| reason | A stable code to branch on in your code |
| violations | Every rule the request broke |
| details | Numbers that explain the block, when there are any |
02
Start from the HTTP status
The status code tells you which kind of rule applied. Start there, then read the reason.
| Status | Meaning | Go to |
|---|---|---|
| 400 | The request is missing required labels | Missing attribution |
| 402 | A budget or credit limit was reached | Rate and budget limits |
| 403 | A policy, tool, size, or guardrail rule blocked it | Access, size, and guardrail sections |
| 429 | A rate limit was reached | Rate and budget limits |
| 502 or 503 | A gateway check could not complete | Retry shortly. For guardrail and rate checks, your policy's fail mode decides whether the request stops or continues. |
03
Access and model rules
These mean the policy does not allow what the request asked for.
| Reason | What it means | Fix |
|---|---|---|
| policy_not_configured | No policy is bound to this key, app, or team | Bind a policy |
| provider_not_allowed | The provider is not on the allow list | Allow it, or choose another provider |
| model_not_allowed | The model is not on the allow list | Allow it, or use an allowed model |
| model_denied | The model is on the deny list | Use another model, or remove it from the deny list |
| tool_not_allowed, tool_denied | The tool is not allowed | Allow the tool on the policy |
| tool_server_not_allowed and related | The tool server is not allowed | Allow the tool server on the policy |
| required_metadata_missing | A label the policy requires was not sent | Send the required team and app labels |
04
Size and agent limits
These mean the request is larger or longer-running than the policy allows.
| Reason | What it means | Fix |
|---|---|---|
| max_input_tokens_exceeded | The prompt is larger than allowed | Send less, or raise the limit |
| max_output_tokens_exceeded | The requested answer length is above the limit | Request a shorter answer, or raise the limit |
| max_tool_calls_exceeded | The agent has made more tool calls than allowed | Raise the limit if the behavior is expected |
| max_retry_count_exceeded, max_loop_iterations_exceeded | The agent has retried or looped too often | Fix the loop, or raise the limit |
05
Rate and budget limits
Rate limits return HTTP 429. Budget and credit blocks return HTTP 402.
| Reason | What it means | Fix |
|---|---|---|
| request_rate_limit_exceeded | Too many requests this minute | Retry shortly, or raise the limit |
| token_rate_limit_exceeded | Too many tokens this minute | Retry shortly, or raise the limit |
| A budget or credit block (402) | The budget or credits are used up | Raise the budget, wait for the next period, or add credits |
06
Guardrail blocks
A guardrail block returns HTTP 403 with the reason gateway_guardrail_blocked.
The violations list names the rule that matched, for example a built-in secret rule such as github_token or one of your own custom rules, which appear as custom_ followed by the rule id. The response never repeats the matched text.
07
Missing attribution
If your setup requires team and app labels and a request has neither, the gateway returns HTTP 400.
Set the team and app on the virtual key, or send them as the x-cloptima-team and x-cloptima-app headers.
08
Handle blocks in your app
Branch on the reason code, not on the message text. The message is for people. The code is stable.
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.cloptima.ai/v1/ai", api_key="clop_vk_...")
try:
reply = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Summarize this ticket"}],
)
except APIStatusError as error:
body = error.response.json()
if body.get("reason") == "request_rate_limit_exceeded":
... # back off and retry
else:
print(body["error"]) # show the readable message to the developer09
Find the rule in the console
Blocked requests appear in the Policy Violations card in the Audit tab.
- 1
Open Audit
Find the blocked request by time and app.
- 2
Match the reason to a setting
The tables above map each reason to the field you would change.
- 3
Confirm the fix in the Request Simulator
Check the change before you save it for everyone.