Error reference
The API is OpenAI-compatible, but validation and plan enforcement add ValGuard-specific statuses and `error.type` values. Use this page to map failures to fixes quickly.
Validation response headers
- X-VG-Validation-Status: pass | warn | block | shadow | stream_passthrough | fail
- X-VG-Healed, X-VG-Healed-Rules, X-VG-Healed-Event-Count, X-VG-Healed-Trace
- X-VG-Request-Id: trace id for dashboards and logs
- X-Request-Id: same id for compatibility
A successful re-ask is stored on the request as reasked_ok. The response header for that call is pass. Response repair is X-VG-Healed, not a validation status. Repair presets are agent settings, not request headers.
| HTTP | error.type | Meaning | Recommended action |
|---|---|---|---|
| 400 | bad_request | Request body or model payload is malformed. | Validate JSON shape and required fields before retrying. |
| 401 | unauthorized | API key is missing, revoked, or invalid. | Use a valid `Authorization: Bearer vg_live_...` key from dashboard API keys. |
| 403 | validation_block | A blocking validator rule failed for this response. | Inspect `details` and tune agent rules, prompt, or payload format. |
| 409 | conflict | Plan or quota operation conflict (for example API key limits). | Review plan limits in billing/settings and retry after adjusting configuration. |
| 422 | validation_error | Input semantics fail validation for the selected route. | Fix payload values and retry with valid request data. |
| 429 | rate_limit_exceeded | Organization has exceeded short-term request limits. | Back off with retry + jitter and monitor plan throughput constraints. |
| 429 | monthly_cap_exceeded | Monthly request allowance has been reached (1 request = 1 complete flow checked against your active rules). | Upgrade your plan, or on a paid subscription enable overage billing in Billing before sending more traffic. Free plans are hard-capped. |
| 402 | token_cap_exceeded | A configured org or per-agent monthly token cap has been exceeded. | Raise org or agent token caps in Billing/Agent settings, or enable token overage on a paid subscription when an org cap is set. Returns 402 (not 429). |
| 500 | internal_error | Unexpected server-side issue in the validation layer or upstream path. | Retry with request id and check status page/logs for ongoing incidents. |