Skip to content

[AI Gateway] Document Guardrails scanner errors #33519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
superhighfives wants to merge 1 commit into
base: production
Choose a base branch
from
+23 −7
Draft

[AI Gateway] Document Guardrails scanner errors #33519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/content/changelog/ai-gateway/2026-09-17-guardrail-scanner-errors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: AI Gateway distinguishes Guardrails scanner errors
description: AI Gateway now separates Guardrails scanner failures from content moderation results.
date: 2026-09-17
---

AI Gateway now separates Guardrails scanner failures from moderation decisions. Applications can respond to billing or service problems without treating content as unsafe.

Scanner credit errors return HTTP `402` with AI Gateway code `2021`. Scanner service errors return HTTP `503` with code `7013` when a **Block** rule applies. Requests with only **Flag** rules continue, and the scanner is recorded as unavailable rather than flagged.

Actual moderation results keep their existing status codes. Provider endpoints return HTTP `424` with code `2016` for blocked prompts or code `2017` for blocked responses. The `/run` API returns HTTP `422` with code `2017` for blocked content.

For the complete error table, refer to [Set up Guardrails](/ai-gateway/features/guardrails/set-up-guardrail/#error-handling-and-blocked-requests).
17 changes: 10 additions & 7 deletions src/content/docs/ai-gateway/features/guardrails/set-up-guardrail.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,18 @@ After enabling Guardrails, you can monitor results through **AI Gateway Logs** i

## Error handling and blocked requests

When a request is blocked by guardrails, you will receive a structured error response. These indicate whether the issue occurred with the prompt or the model response. Use error codes to differentiate between prompt versus response violations.
Guardrails return structured errors when content is blocked. They also return errors when a scan cannot run. Provider-specific endpoints and the `/run` API use different moderation codes. The HTTP status and AI Gateway code identify the result:

- **Prompt blocked**
- `"code": 2016`
- `"message": "Prompt blocked due to security configurations"`
| Result | Provider-specific endpoints | `/run` API |
| -------------------------- | --------------------------- | -------------- |
| Prompt blocked | `424` / `2016` | `422` / `2017` |
| Response blocked | `424` / `2017` | `422` / `2017` |
| Scanner needs more credits | `402` / `2021` | `402` / `2021` |
| Scanner unavailable | `503` / `7013` | `503` / `7013` |

- **Response blocked**
- `"code": 2017`
- `"message": "Response blocked due to security configurations"`
All structured error responses use `name: "AiGatewayError"`. The internal code is available in `internalCode` and the nested `error` field.

Scanner failures follow the configured Guardrails action. A scanner failure returns `503` when any rule for that phase uses **Block**. If all rules use **Flag**, the request continues and the scanner is recorded as unavailable. A scanner credit error always returns `402`.

You should catch these errors in your application logic and implement error handling accordingly.

Expand Down
Loading