Troubleshoot refusals
Find the reason for a Gateway refusal, review the matching configuration, and verify recovery on a new request.
Current admission behavior
On supported Gateway paths, rate-limit, access, and budget checks run in that order. Configuration and availability depend on the deployment.
| Control | Supported result | Boundary |
|---|---|---|
| Active model/provider deny | HTTP 403 refusal when a rule matches | With no matching deny, admission is allowed by default |
| Requests-per-minute limit | HTTP 429 refusal | Counting-backend failure can admit traffic on the documented path |
| Hard budget | HTTP 402 refusal | Applies only on the configured supported admission path |
alert_only budget | Does not block admission | A threshold does not establish that a notification was delivered |
Hard-budget behavior depends on the deployed accounting path. A matching hard budget can fail closed when accounting is unavailable; some paths permit a bounded last-known-spend grace. Confirm the deployed path and failure behavior before enabling a hard limit. See Policy and enforcement boundaries.
Configuration and denial evidence
- Record the client's response status, model, provider and request time. Keep credentials out of diagnostic material.
- Open Gateway → Budgets, Gateway → Rate Limits or Gateway → Access, according to the response: HTTP 402, 429 or 403.
- Inspect Recent denials for the corresponding reason. Compare the time, scope and affected model/provider with the failed request.
- Match the denial's configured resource to the saved budget, rate limit or access rule. Review its active status, scope, filters and limit before changing it.
- Keep the client response and denial record as separate evidence unless a captured request link establishes the connection. Current denial evidence pointers marked
not_capturedsupply no request or session link.
Budget denial amounts are in USD after conversion from nano-USD. Rate-limit values are counts, not dollar amounts. An access denial shows HTTP 403. Do not compare values across these reasons as if they used the same unit.
Atlas's budgets table can show scope, cap/window, soft threshold, action, active/disabled state, and recent denials. A saved configuration does not prove it was applied to a request. Use the client response and available metadata to identify the affected request path; a similar configuration or timestamp alone does not establish request correlation.
Denial telemetry is best effort and can drop. A missing record is not proof of admission or refusal, and the table is not a durable audit ledger. A configured threshold is not proof of an alert. Default allow or an Admin role does not establish a human approval workflow.
Recovery
Identify the configured budget or access rule that refused the request. An authorized administrator can review the configuration or the relevant window. Do not promise a universal recovery delay or assume that every refusal clears at month start. Verify the updated configuration on a new request through the affected path.