persona-common-errors

persona common errors | sed 's/\b(.)/\u\1/g'

Overview

401 invalid key, 422 invalid template, webhook HMAC mismatch, inquiry already completed, rate limit 429.

Prerequisites

• Completed persona-install-auth setup
• Valid Persona API key (sandbox or production)

Instructions

Error 1: 401 Unauthorized

{"errors":[{"status":"401","title":"Not Authorized"}]}

Fix: Verify API key starts with persona_sandbox_ or persona_production_. Check Authorization: Bearer <key> header format.

Error 2: 422 Invalid Inquiry Template

{"errors":[{"status":"422","title":"Invalid inquiry-template-id"}]}

Fix: Verify template ID format is itmpl_*. Templates are environment-specific (sandbox templates only work with sandbox keys).

Error 3: Webhook Signature Mismatch

HMAC verification failed — expected abc123, got def456

Fix: Ensure you're using the raw request body (not parsed JSON) for HMAC computation. Use express.raw() middleware.

Error 4: 429 Rate Limited

{"errors":[{"status":"429","title":"Rate limit exceeded"}]}

Fix: Implement exponential backoff. Check Retry-After header. See persona-rate-limits.

Error 5: Inquiry Already Completed

{"errors":[{"status":"409","title":"Inquiry is already in a terminal state"}]}

Fix: Check inquiry status before attempting operations. Use the resume endpoint only for created or pending inquiries.

Error 6: 404 Inquiry Not Found

{"errors":[{"status":"404","title":"Not Found"}]}

Fix: Verify inquiry ID format is inq_*. Sandbox inquiries are not accessible with production keys.

Output

• Error identified from API response
• Targeted fix applied
• Verified resolution

Error Handling

HTTP Code	Meaning	Retryable
400	Bad request	No
401	Invalid API key	No — fix key
404	Resource not found	No
409	Conflict (terminal state)	No
422	Validation error	No — fix request
429	Rate limited	Yes
500+	Server error	Yes

Resources

• Persona API Reference

Next Steps

For debugging, see persona-debug-bundle.