Docs
Errors and recovery
Error handling patterns for resilient age verification integrations.
Key points
- Classify errors by retryability and user-facing impact.
- Provide deterministic recovery actions for each error class.
- Expose structured logs for rapid debugging and support escalation.
- Keep customer messaging clear for recoverable versus terminal failures.
How this works
Errors and recovery works best when the backend owns final decisions, retries are deterministic, and support teams know exactly how edge cases are handled.
Quickstart snippet
curl -X POST "https://ageverify.dev/api/v1/verification-sessions" \
-H "Authorization: Bearer $AGEVERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operatorId":"00000000-0000-4000-8000-000000000001","userId":"user_123"}'Common failure modes
- Expired or missing session token before SDK initialization starts.
- Duplicate create/finalize calls without stable idempotency keys.
- Webhook signature validation failures or replayed payload handling gaps.
- Billing-state blocks that prevent new verification sessions from starting.
Observability checks
- Track session creation success/failure and median time-to-finalization.
- Monitor webhook delivery health, retries, and signature-failure counts.
- Alert on spikes in retryable errors and repeated no-pass outcomes by device/region.
- Reconcile meter events with finalized session outcomes on a scheduled cadence.
Next doc to read
Quick checklist
- Define where verification is required and who owns policy updates.
- Keep access decisions server-authoritative and auditable.
- Track retries and no-pass outcomes by device and region.
- Document escalation handling before launch.
What to verify
- Explicit error taxonomy with retryability guidance.
- Consistent user and operator recovery pathways.
- Structured logging for operational debugging and audits.
Useful resources
- Error-code matrix
- Recovery decision tree
- Incident response quick-reference table
Frequently asked questions
How should errors be grouped for implementation?
Group by retryability and user impact so systems can apply deterministic recovery behavior.
Which errors should not be retried immediately?
Authentication and validation failures typically require correction rather than immediate blind retry loops.
How should customer-facing messaging differ by error type?
Provide clear, action-oriented messaging for recoverable states and explicit guidance for escalation-only outcomes.
What logging is required for troubleshooting?
Capture request identifiers, error categories, and contextual state transitions without exposing sensitive credentials.
How should teams validate error handling before launch?
Run scenario tests covering auth failures, validation errors, network timeouts, and duplicate event handling.