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

.