Error Codes

Error Responses

Your webhook should return appropriate HTTP status codes. Token Vault maps these to user-facing errors:

All error responses should include a JSON body:

{
  "error": "auth_failed",
  "message": "HMAC signature invalid"
}

Retry & Timeout Policy

Token Vault uses the following retry strategy for webhook calls:

Timeout:    10 seconds per request (30 seconds for /v1/proxy)
Retries:    2 retries (3 total attempts)
Backoff:    1s after first failure, 3s after second

Attempt 1:  Call webhook
Attempt 2:  Wait 1s → retry (only on 5xx or timeout)
Attempt 3:  Wait 3s → retry (only on 5xx or timeout)

No retry on 4xx errors (400, 401, 403, 410, 429)

A 429 is never retried: Token Vault reads your Retry-After header (clamped to 1–900 seconds) and propagates the backoff to the calling agent. After 5 consecutive failed calls to the same webhook host (timeout, 5xx, or 429), Token Vault opens a circuit breaker for 30 seconds to 10 minutes (doubling on repeated opens) and fails fast with a 503 instead of dialing your webhook. On the /v1/proxy path only connection-level failures (timeout/unreachable) count toward the circuit, since HTTP statuses there may be upstream responses passed through.