ERROR CONTRACT
Branch on stable codes, not message text.
Every JSON failure includes success=false, one or more error_codes, and a request_id suitable for support correlation without exposing credentials.
Token and binding errors
Do not retry the same response token after a terminal token error.
- invalid-token
- expired-token
- replayed-token
- hostname-mismatch
- action-mismatch
Configuration and challenge errors
Correct the site or integration configuration before retrying.
- invalid-site-key
- invalid-secret
- challenge-failed
- unsupported-version
Capacity and dependency errors
A 429 response is rate-limited. A 503 internal-error means a security dependency is unavailable and verification failed closed.
- Respect Retry-After when present
- Use bounded exponential backoff only for safe issuance requests
- Never treat timeout or 503 as a successful verification