Errors and recovery - DataVibe Documentation

Policy outcomes return HTTP 200 with a gate status. Transport and platform failures use non-2xx responses with a structured error envelope.

Condition	Response	Recovery
Invalid or revoked key	`401`	Replace the credential; do not retry unchanged.
IP not allowlisted	`403 ip_not_allowlisted`	Add the caller’s IP in Security → API keys, or disable the allowlist.
Key lacks required scope	`403 insufficient_api_key_scope`	Reissue the key with the needed capability.
Workspace disabled	`403 workspace_disabled`	Contact the workspace owner.
Account is alpha-waitlisted	`403 alpha_waitlist`	Wait for alpha access, or use the stateless preview.
Subscription canceled or past due	`402/403 subscription_required`	Resolve billing, then retry.
Invalid payload	`422`	Correct the request fields.
Plan quota exhausted	`429 PLAN_QUOTA_EXCEEDED`	Follow the `X-Usage-*` headers or upgrade.
Daily token budget exhausted	`429 GENERATE_TOKEN_QUOTA_EXCEEDED`	Wait for the daily reset or upgrade.
Burst rate limited	`429 GATE_RATE_LIMITED`	Honor `Retry-After` and retry with backoff.
Rate-limit store unavailable	`503 RATE_LIMIT_EXCEEDED`	Retry after the indicated delay. Distinct from `GATE_RATE_LIMITED`: this means the limiter itself is down, not that you hit a limit.
Fail-closed platform failure (DB pool, workspace context, snapshot resolve, insert)	`503 SNAPSHOT_UNAVAILABLE`	Retry after the indicated delay with the same idempotency key. This is the default code for any fail-closed 503 on the gate path, not only a missing snapshot.
Dispatch/provider failure	Gate status `FAILED`	Inspect metadata; verify no delivery occurred before retrying.

Rate and quota responses may include, in the response body:

code
message
request_id
next_step ("upgrade", "retry", or "wait")

And in response headers:

X-Usage-Scope, X-Usage-Plan, X-Usage-Limit, X-Usage-Total, X-Usage-Remaining, X-Usage-Reset-At: monthly plan/token quota.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset: the separate per-org burst limiter. Present on every gate request, not only 429s.
X-Request-Id
Retry-After: seconds, on 429/503 only.

There is no reset_at field in the response body. Reset timing is header-only: X-Usage-Reset-At for plan/token quota, X-RateLimit-Reset for the burst limiter.

Safe error logging

Log the error code, request ID, action ID, and idempotency key. Do not log full API keys, sensitive recipient content, or unredacted policy matches.

A scanner exception fails closed as a blocking decision. A missing policy snapshot returns 503; DataVibe does not evaluate without an auditable snapshot.

​Safe error logging

Safe error logging