Developer documentation

Errors, rate limits, and timeouts

HTTP errors, deadline exhaustion, and rate limits are transport or platform failures. They are never mapped to allow or deny—your integration must branch on status before reading result.

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.

Retryable conflicts

409 EVALUATION_PENDING means an earlier request with the same idempotency key is still running. error.retryable is true: retry with the same key and payload to receive its result.

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.