About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/persona-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill persona-common-errors. Copyright stays with the author (MIT).

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

Name: persona-common-errors
Author: jeremylongshore

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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-persona-commo-5c12cc/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-persona-commo-5c12cc.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-persona-commo-5c12cc",
  "kind": "skill",
  "name": "persona-common-errors",
  "description": "Fix top Persona API errors: 401, 422, webhook signature failures, inquiry state issues. Use when working with Persona identity verification. Trigger with phrases like \"persona common-errors\", \"persona common-errors\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "saas",
      "persona",
      "identity",
      "kyc",
      "verification",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Fix top Persona API errors: 401, 422, webhook signature failures, inquiry state issues. Use when working with Persona identity verification. Trigger with phrases like \"persona common-errors\", \"persona common-errors\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/persona-common-errors/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/persona-common-errors/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/persona-common-errors/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Grep,",
      "Bash(curl:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# persona common errors | sed 's/\\b\\(.\\)/\\u\\1/g'\n\n## Overview\n\n401 invalid key, 422 invalid template, webhook HMAC mismatch, inquiry already completed, rate limit 429.\n\n## Prerequisites\n\n- Completed `persona-install-auth` setup\n- Valid Persona API key (sandbox or production)\n\n## Instructions\n\n### Error 1: 401 Unauthorized\n\n```\n{\"errors\":[{\"status\":\"401\",\"title\":\"Not Authorized\"}]}\n```\n\n**Fix:** Verify API key starts with `persona_sandbox_` or `persona_production_`. Check `Authorization: Bearer <key>` header format.\n\n### Error 2: 422 Invalid Inquiry Template\n\n```\n{\"errors\":[{\"status\":\"422\",\"tit",
  "cost": {
    "context_tokens": 560
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-persona-commo-5c12cc/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.