Developer documentation

Errors, rate limits, and timeouts

Technical failures are explicit errors. Veltor never converts them into allow or deny.

Error envelope

Errors contain error.code, error.message, error.field when safe, error.retryable, and request_id. Every HTTP response also includes X-Request-ID.

{"error":{"code":"OAUTH_SCOPE_REQUIRED","message":"Authorize the policies:write scope, then retry the request.","field":null,"retryable":false},"request_id":"request-id"}

Rate limits

A 429 response includes Retry-After. Wait for that interval. Retry a mutation only with its original idempotency key.

Deadlines

Evaluations have a 1.5-second server deadline. Normal reads and configuration mutations have a five-second deadline. Deadline exhaustion returns 504 DEADLINE_EXCEEDED with retryable true.