Skip to main content
This page is your reference when something doesn’t go to 200. Use the Verdicts page for what to do with the verdict inside a 200 response; this page is for protocol failures.

​
Error codes

StatuscodeWhenWhat to do
200,Success. Verdict in the body.Read verdict and act accordingly.
400APP_ID_REQUIREDX-Antidote-App-Id header missing.Provision an App and pass its UUID.
400APP_NOT_FOUNDApp UUID does not belong to the caller’s workspace.Check the App ID and the workspace.
400APP_TOKEN_REQUIRED / APP_TOKEN_INVALIDApp requires a signed token and one wasn’t supplied or doesn’t verify.Issue a fresh token via …/apps/{id}/tokens.
400CUSTOM_PARAM_REQUIREDA required custom param is missing on a scan call.Include it in custom_params.
400,Malformed request, or streaming requested on a non‑streamed route.Fix the body. See detail.
401,Missing or invalid credentials.Check the X-API-Key header.
402QUOTA_EXCEEDEDWorkspace license‑call quota exceeded.Body includes usage snapshot and upgrade_url. Wait until reset or upgrade.
403,Caller lacks the required permission scope.Add runtime_security.scan (or .view / .manage) to the API key.
404,Feature not licensed for this workspace.Module is invisible to unlicensed tenants.
410APP_ARCHIVEDApp was deleted or archived.Switch to a live App.
422,Schema validation failed.See detail for the array of field errors.
423APP_DISABLEDApp has status="disabled".Re‑enable in the dashboard.
429,Per‑second rate limit hit.Back off. Limits are per workspace, not per key.
429APP_QUOTA_EXCEEDEDApp’s hourly or daily event cap reached.Back off until Retry-After, or raise max_events_per_hour / _per_day on the App.
503,Firewall disabled, starting up, or metering store unavailable.Retry with backoff. If persistent, check /health and contact support.

​
Rate limits

Three layers stack: per‑second limits, per‑App quotas, and license quota.

​
Per‑second rate limits

EndpointLimit
/scan/input, /scan/output, /scan/tool-call20 / second / workspace.
/scan/batch4 / second / workspace.
/config PUT6 / minute / workspace.
When you exceed these limits you get 429 with no code field and a Retry-After header.

​
Per‑App event quotas

Set max_events_per_hour and / or max_events_per_day on the App. When hit, the response is:
  • HTTP 429
  • code: "APP_QUOTA_EXCEEDED"
  • Retry-After: 60 (hourly) or 3600 (daily)
Useful for capping spend on staging Apps and for isolating noisy customers under the same workspace.

​
License quota

Each call consumes one unit from the workspace’s monthly call quota. Batch items count individually. The 402 response body: 
{
  "code": "QUOTA_EXCEEDED",
  "message": "Runtime Security call quota exceeded for this license.",
  "usage": {"used": 1000000, "limit": 1000000, "period_end": "2026-05-01T00:00:00Z"},
  "upgrade_url": "/settings/license"
}

​
Fail‑closed behaviour

If the firewall service is down, scan endpoints fail with 503. Your application should treat this as deny‑by‑default. Letting prompts through unscored is exactly what the firewall is meant to prevent. The /health endpoint reports liveness; integrate it into your readiness probe if you operate the firewall in self‑hosted mode.

​
FAQ

The verdict is information your application needs: blocked_reason, uuid, the score, the matching phrase. Returning 200 with the verdict in the body keeps that contract clean. Non‑200 codes are reserved for protocol failures (auth, rate limit, quota) where the client genuinely cannot retrieve a verdict.
redacted_text has any detected PII replaced with <CATEGORY> markers. On verdict: allow, redacted_text equals the original. On redact, forward redacted_text to your model. On block, neither field should be sent; surface a refusal to your user.
Not directly, but you can set the redact threshold very high (e.g. 1.1) so the API surface stays consistent without ever producing a redact verdict from injection score. Custom PII rules can be removed individually via the custom‑rules endpoint.
Check injection.meta.normalized in the response. When the firewall canonicalised the input (NFKC, zero‑width strip, Cyrillic confusables undo, leet undo), this flag is true and injection.meta.phrase_hits shows what matched.
The dashboard’s Runtime Security tab shows verdict timelines, the event log, and the drift surface. Or hit /analytics and /events programmatically. See Observability.
Recommended. Cloning a production App into a staging_… clone gives you separate quotas, separate event streams, and config‑version history that doesn’t pollute production drift charts. Use POST …/apps/{id}/clone to seed it.
No. Apps are workspace‑scoped, that’s the boundary both the API key and the App‑Id header check. Cross‑workspace traffic is rejected as APP_NOT_FOUND regardless of credentials.
Run both for a few days. Point a fraction of traffic at the proxy via a feature flag and watch the verdict mix on the dashboard for both paths. Once the proxy mix matches what the scan API produced, flip the rest.