Skip to content
CortexDocs

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.

Compare recent rate-limit denial counts with their configured limitsMobile preview. Enlarge for the full view.Open in Cortex
  • 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

  1. Use the response status to open Access & limits → Budgets, Access & limits → Rate Limits or Security → Access rules.
  2. Inspect Recent denials for the corresponding reason.
  3. Compare the event time, affected model/provider and configured resource with the failed request.
  4. Find that resource in the saved list. Review its active status, scope, filters and limit before changing it.
  5. 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 responseReturned reasonInspect and repair
HTTP 402budget_exceededInspect the matching hard budget, scope, filters, carve-outs and metering state. Review the cap, action or status in Manage budgets.
HTTP 429rate_limitedInspect the matching RPM limit and recent traffic. Reduce request frequency; review the RPM or disable the intended record in Set rate limits.
HTTP 403model_access_deniedInspect 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

  1. Have an authorized administrator make the relevant configuration change from the linked guide.
  2. Refresh the saved list and check the intended resource, scope, filters, action and status.
  3. Allow for configuration delivery on the affected path. Do not assume a universal recovery delay or a calendar-month reset.
  4. Send a new controlled request through the same client path and inspect the returned status.
  5. 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

SymptomNext action
The management view fails to loadRetry the read before changing configuration. A failed read does not mean the history is empty.
No denial matches the responseRetain 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 linkKeep 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 resultCheck 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.