Troubleshoot refusals
Find the reason for a Gateway refusal, review the matching configuration, and verify recovery on a new request.
Identify the control behind a refused request, change the matching resource when appropriate and verify a new request.
Before you begin
Required
- Client response
Keep the response status and request time.
- Request context
Keep the model, provider and affected client path for comparison.
Optional
- Admin access for configuration changes
An Admin can change the matching configuration. Read access alone does not permit a repair.
Keep credentials out of diagnostic material.
- Supported Gateway paths check rate limits, model and provider access rules, and hard budgets in that order.
- Configuration and failure behavior depend on the deployment. See Policy and enforcement boundaries.
Find the refusing resource
- Use the response status to open Access & limits → Budgets, Access & limits → Rate Limits or Security → Access rules.
- Inspect Recent denials for the corresponding reason.
- Compare the event time, affected model/provider and configured resource with the failed request.
- Find that resource in the saved list. Review its active status, scope, filters and limit before changing it.
- Open a captured-request link only when one is supplied. If the denial has no captured-request link, keep it separate from session activity; a similar timestamp alone does not establish that they are the same request.
| Client response | Returned reason | Inspect and repair |
|---|---|---|
| HTTP 402 | budget_exceeded | Inspect the matching hard budget, scope, filters, carve-outs and metering state. Review the cap, action or status in Manage budgets. |
| HTTP 429 | rate_limited | Inspect the matching RPM limit and recent traffic. Reduce request frequency; review the RPM or disable the intended record in Set rate limits. |
| HTTP 403 | model_access_denied | Inspect the active model/provider deny. Review other matching rules before disabling the intended deny in Restrict access. |
Keep authentication failures separate from model-access policy. For capture-identity, model, provider and endpoint errors, use the Gateway API reference. Keep the returned details and request context when asking an administrator to investigate; exclude credentials.
- Budget denial amounts are displayed in USD.
- Rate-limit values are counts.
- The opening rate-limit history shows counts against limits, not a current counting-window balance.
Compare accounting and reporting
Captured estimated spend is not an authoritative admission balance. Budget scope, window, pricing and accounting freshness determine what a counter means.
Concurrent requests and in-flight usage must be considered when assessing a spending ceiling. Retries, incomplete responses and unknown prices can affect provider charges. A sum of local device estimates does not establish a shared company-wide balance. See Configured limits and reporting estimates.
Repair and verify
- Have an authorized administrator make the relevant configuration change from the linked guide.
- Refresh the saved list and check the intended resource, scope, filters, action and status.
- Allow for configuration delivery on the affected path. Do not assume a universal recovery delay or a calendar-month reset.
- Send a new controlled request through the same client path and inspect the returned status.
- Review any new denial against its own configured resource. A different matching control can still refuse the request.
Use only the headers documented for your serving path. A reporting estimate does not define a remaining-limit or reset header; do not infer retry timing from a chart. Bound retries in the caller and account for retries already performed by the SDK.
- Alert only permits the request and does not confirm that a notification was delivered.
- If current budget usage cannot be checked, requests may stop or continue briefly using the last known spend, depending on your deployment. Ask your administrator to confirm the applicable behavior.
- A failure to check the request count can allow traffic to continue despite a configured rate limit.
- Confirm the applicable deployment behavior. A saved budget or reporting chart does not establish fail-closed behavior.
If evidence is missing
| Symptom | Next action |
|---|---|
| The management view fails to load | Retry the read before changing configuration. A failed read does not mean the history is empty. |
| No denial matches the response | Retain the response, time and affected path. Denial telemetry is best effort and can drop; no record does not prove admission or refusal. |
| The denial has no captured-request link | Keep the client response and resource context as separate evidence. Do not infer a session from a similar timestamp. |
| A refreshed record differs from the request result | Check other matching controls, configuration delivery and the deployed metering or counting path. |
- Recent denials are not a durable audit ledger.
- A saved configuration or threshold does not establish application or notification delivery.