Errors and rate limits

Error formats

• Guard always answers with a verdict: { "allowed": false, "reason": "..." }.
• Ingest, finalize and config answer errors as { "error": "...", "reason": "...", "details": { ... } }; reason and details are optional.

Guard

Status	allowed	Reasons	What to do
200	true	none, or system_failure* with bypassed: true	Continue with transformed_input
200	false	pii_detection_unavailable, semantic_authority_unavailable, *_unavailable	Fail-closed system could not complete the check; do not call the model, retry later
400	false	invalid_payload	Fix the request (unknown field, wrong type, value too long)
401	false	unauthorized, system_id_mismatch	Check the API key and system_id
403	false	Policy reasons, see Guard API; system_suspended	Do not call the model; show the reason
413	false	payload_too_large	Reduce the body below 4 MiB
429	false	rate_limited, rate_limited_burst, daily_limit, hourly_token_limit, daily_token_limit	Wait for Retry-After
500	false	server_error	Retry with backoff
503	false	system_failure, system_failure_db_unavailable, semantic_authority_unavailable, circuit_breaker	Retry with backoff; the system is fail-closed or stopped

Ingest

Status	Meaning
200	Stored (success: true, event_id)
400	Invalid payload (details lists the fields) or stale_event_timestamp / invalid_timestamp
401	Missing or invalid key, or system_id mismatch
403	System paused: Access denied: AI system suspended (Kill Switch active).
409	replay_detected: an event with this event_id is already stored; treat as success on a retry
413	Body over 4 MiB
429	Rate limit or daily limit of the system
503	A dependency is unavailable; retry

/api/v1/ingest/finalize adds 404 (event_not_found) when no event with that client_event_id exists.

Rate limits

Limits apply per AI system: requests per minute, an optional daily request cap, optional hourly and daily token caps (set in Guardrails → Service Protection) and a short burst limit. A limited response is 429 with:

Header	Meaning
Retry-After	Seconds to wait
X-RateLimit-Limit	Allowed requests in the window
X-RateLimit-Remaining	Requests left in the window

In Shadow Mode, Guard records limit hits as simulated blocks instead of enforcing them.

Retries

• 429: wait at least Retry-After, then retry with exponential backoff and jitter.
• 5xx: retry with capped exponential backoff, for example 250 ms, 500 ms, 1 s, 2 s, capped at 5 s.
• Ingest: retry with the same event_id.
• Guard: a retry is a new check. Reuse the client_event_id so the activity log stays linked.

The official SDKs already retry: Guard up to three attempts on network errors, timeouts and 5xx; ingest on 5xx and 429.

Useful response headers

Header	Meaning
x-correlation-id	Your correlation id, or one generated by AgentID
X-AgentID-Latency	Server processing time in ms
X-AgentID-Status: BYPASSED_INFRA_ERROR	Guard skipped the check in a fail-open system