Docs/API Reference/Error Codes

HTTP Error Codes

Complete reference for every HTTP status code the Guardrail API returns, with causes and resolution steps.

200OK

Request was evaluated successfully. Inspect risk_score and status in the response body for the safety verdict.

Resolution: Normal successful response.

401Unauthorized

Authentication failed. The API key is missing, malformed, or has been revoked.

Resolution: Check that your Authorization header is set: `Authorization: Bearer sk_...`

402Payment Required

Your account credit balance is below $0.01 and cannot fund this request.

Resolution: Top up your balance via the Billing dashboard or upgrade your subscription tier.

422Unprocessable Entity

The request body is malformed or missing required fields. For compliance, we return a generic message without echoing any input.

Resolution: Ensure both `agent_id` (string) and `proposed_text` (string) are present in the JSON body.

429Too Many Requests

You have exceeded the rate limit for your tier. Sandbox is limited to 10 requests per minute.

Resolution: Wait for the 60-second window to reset, or upgrade to Startup/Scale for unlimited throughput.

500Internal Server Error

An unexpected error occurred on our infrastructure. The request was not evaluated or billed.

Resolution: Retry the request with exponential backoff starting at 2 seconds. Contact support if persistent.

502 / 503Bad Gateway / Unavailable

A transient infrastructure issue. Our AI processing layer may be restarting.

Resolution: Retry with exponential backoff. Check status.guardrail.ai for incident reports.

Handling errors in production

For non-critical AI outputs, we recommend a fail-open strategy: if Guardrail returns a 5xx error, pass the content through rather than breaking your user experience. For high-stakes scenarios (medical, legal, financial), implement fail-closed and serve a safe fallback message.