Persona Common Errors

Overview

Quick reference for the top 10 most common Persona errors and their solutions.

Prerequisites

• Persona SDK installed
• API credentials configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message and code in your logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Output

• Identified error cause
• Applied fix
• Verified resolution

Error Handling

Authentication Failed

Error Message:

Authentication error: Invalid API key

Cause: API key is missing, expired, or invalid.

Solution:

# Verify API key is set
echo $PERSONA_API_KEY

Rate Limit Exceeded

Error Message:

Rate limit exceeded. Please retry after X seconds.

Cause: Too many requests in a short period.

Solution:

Implement exponential backoff. See persona-rate-limits skill.

Network Timeout

Error Message:

Request timeout after 30000ms

Cause: Network connectivity or server latency issues.

Solution:

// Increase timeout
const client = new Client({ timeout: 60000 });

Examples

Quick Diagnostic Commands

# Check Persona status
curl -s https://status.persona.com

# Verify API connectivity
curl -I https://api.persona.com

# Check local configuration
env | grep PERSONA

Escalation Path

1. Collect evidence with persona-debug-bundle
2. Check Persona status page
3. Contact support with request ID

Resources

• Persona Status Page
• Persona Support
• Persona Error Codes

Next Steps

For comprehensive debugging, see persona-debug-bundle.

Persona Core Workflow A

Overview

Primary money-path workflow for Persona. This is the most common use case.

Prerequisites

• Completed persona-install-auth setup
• Understanding of Persona core concepts
• Valid API credentials configured

Instructions

Step 1: Initialize

// Step 1 implementation

Step 2: Execute

// Step 2 implementation

Step 3: Finalize

// Step 3 implementation

Output

• Completed Core Workflow A execution
• Expected results from Persona API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Common Variations

• Variation 1: Description
• Variation 2: Description

Resources

• Persona Documentation
• Persona API Reference

Next Steps

For secondary workflow, see persona-core-workflow-b.

Persona Core Workflow B

Overview

Secondary workflow for Persona. Complements the primary workflow.

Prerequisites

• Completed persona-install-auth setup
• Familiarity with persona-core-workflow-a
• Valid API credentials configured

Instructions

Step 1: Setup

// Step 1 implementation

Step 2: Process

// Step 2 implementation

Step 3: Complete

// Step 3 implementation

Output

• Completed Core Workflow B execution
• Results from Persona API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Error Recovery

// Error handling code

Resources

• Persona Documentation
• Persona API Reference

Next Steps

For common errors, see persona-common-errors.

Persona Cost Tuning

Overview

Optimize Persona costs through smart tier selection, sampling, and usage monitoring.

Prerequisites

• Access to Persona billing dashboard
• Understanding of current usage patterns
• Database for usage tracking (optional)
• Alerting system configured (optional)

Pricing Tiers

Cost Estimation

interface UsageEstimate {
  requestsPerMonth: number;
  tier: string;
  estimatedCost: number;
  recommendation?: string;
}

function estimatePersonaCost(requestsPerMonth: number): UsageEstimate {
  if (requestsPerMonth <= 1000) {
    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
  }

  if (requestsPerMonth <= 100000) {
    return { requestsPerMonth, tier: 'Pro', estimatedCost: 99 };
  }

  const proOverage = (requestsPerMonth - 100000) * 0.001;
  const proCost = 99 + proOverage;

  return {
    requestsPerMonth,
    tier: 'Pro (with overage)',
    estimatedCost: proCost,
    recommendation: proCost > 500
      ? 'Consider Enterprise tier for volume discounts'
      : undefined,
  };
}

Usage Monitoring

class PersonaUsageMonitor {
  private requestCount = 0;
  private bytesTransferred = 0;
  private alertThreshold: number;

  constructor(monthlyBudget: number) {
    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
  }

  track(request: { bytes: number }) {
    this.requestCount++;
    this.bytesTransferred += request.bytes;

    if (this.estimatedCost() > this.alertThreshold) {
      this.sendAlert('Approaching Persona budget limit');
    }
  }

  estimatedCost(): number {
    return estimatePersonaCost(this.requestCount).estimatedCost;
  }

  private sendAlert(message: string) {
    // Send to Slack, email, PagerDuty, etc.
  }
}

Cost Reduction Strategies

Step 1: Request Sampling

function shouldSample(samplingRate = 0.1): boolean {
  return Math.random() < samplingRate;
}

// Use for non-critical telemetry
if (shouldSample(0.1)) { // 10% sample
  await personaClient.trackEvent(event);
}

Step 2: Batching Requests

// Instead of N individual calls
await Promise.all(ids.map(id => personaClient.get(id)));

// Use batch endpoint (1 call)
await personaClient.batchGet(ids);

Step 3: Caching (from P16)

• Cache frequently accessed data
• Use cache inva

Persona Debug Bundle

Overview

Collect all necessary diagnostic information for Persona support tickets.

Prerequisites

• Persona SDK installed
• Access to application logs
• Permission to collect environment info

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# persona-debug-bundle.sh

BUNDLE_DIR="persona-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Persona Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment Info

# Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "PERSONA_API_KEY: ${PERSONA_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 3: Gather SDK and Logs

# SDK version
npm list @persona/sdk 2>/dev/null >> "$BUNDLE_DIR/summary.txt"

# Recent logs (redacted)
grep -i "persona" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"

# Configuration (redacted - secrets masked)
echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
cat .env 2>/dev/null | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE_DIR/config-redacted.txt"

# Network connectivity test
echo "--- Network Test ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "API Health: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code}" https://api.persona.com/health >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 4: Package Bundle

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Output

• persona-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
• summary.txt - Environment and SDK info
• logs.txt - Recent redacted logs
• config-redacted.txt - Configuration (secrets removed)

Error Handling

# Add Persona secrets to Vercel
vercel secrets add persona_api_key sk_live_***
vercel secrets add persona_webhook_secret whsec_***

# Link to project
vercel link

# Deploy preview
vercel

# Deploy production
vercel --prod

{
  "env": {
    "PERSONA_API_KEY": "@persona_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

app = "my-persona-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

# Set Persona secrets
fly secrets set PERSONA_API_KEY=sk_live_***
fly secrets set PERSONA_WEBHOOK_SECRET=whsec_***

# Deploy
fly deploy

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]

#!/bin/bash
# deploy-cloud-run.sh

PROJECT_ID="${GOOGLE_CLOUD_PROJECT}"
SERVICE_NAME="persona-service"
REGION="us-central1"

# Build and push image
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME

# Deploy to Cloud Run
gcloud run deploy $SERVICE_NAME \
  --image gcr.io/$PROJECT_ID/$SERVICE_NAME \
  --region $REGION \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets=PERSONA_API_KEY=persona-api-key:latest

// config/persona.ts
interface PersonaConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  webhookSecret?: string;
}

export function getPersonaConfig(): PersonaConfig {
  const env = process.env.NODE_ENV || 'development';

  return {
    apiKey: process.env.PERSONA_API_KEY!,
    environment: env as PersonaConfig['environment'],
    webhookSecret: process.env.PERSONA_WEBHOOK_SECRET,
  };
}

// api/health.ts
export async function GET() {
  const personaStatus = await checkPersonaConnection();

  return Response.json({
   

import { PersonaClient } from '@persona/sdk';

const client = new PersonaClient({
  apiKey: process.env.PERSONA_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

Success! Your Persona connection is working.

import { PersonaClient } from '@persona/sdk';

const client = new PersonaClient({
  apiKey: process.env.PERSONA_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

from persona import PersonaClient

client = PersonaClient()

# Your first API call here

# Node.js
npm install @persona/sdk

# Python
pip install persona

# Set environment variable
export PERSONA_API_KEY="your-api-key"

# Or create .env file
echo 'PERSONA_API_KEY=your-api-key' >> .env

// Test connection code here

import { PersonaClient } from '@persona/sdk';

const client = new PersonaClient({
  apiKey: process.env.PERSONA_API_KEY,
});

from persona import PersonaClient

client = PersonaClient(
    api_key=os.environ.get('PERSONA_API_KEY')
)

my-persona-project/
├── src/
│   ├── persona/
│   │   ├── client.ts       # Persona client wrapper
│   │   ├── config.ts       # Configuration management
│   │   └── utils.ts        # Helper functions
│   └── index.ts
├── tests/
│   └── persona.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
└── package.json

# Copy environment template
cp .env.example .env.local

# Install dependencies
npm install

# Start development server
npm run dev

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

import { describe, it, expect, vi } from 'vitest';
import { PersonaClient } from '../src/persona/client';

describe('Persona Client', () => {
  it('should initialize with API key', () => {
    const client = new PersonaClient({ apiKey: 'test-key' });
    expect(client).toBeDefined();
  });
});

vi.mock('@persona/sdk', () => ({
  PersonaClient: vi.fn().mockImplementation(() => ({
    // Mock methods here
  })),
}));

# Enable verbose logging
DEBUG=PERSONA=* npm run dev

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedPersonaRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

import DataLoader from 'dataloader';

const personaLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from Persona
    const results = await personaClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  personaLoader.load('id-1'),
  personaLoader.load('id-2'),
  personaLoader.load('id-3'),
]);

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new PersonaClient({
  apiKey: process.env.PERSONA_API_KEY!,
  httpAgent: agent,
});

async function* paginatedPersonaList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.persona.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/persona-integration app=image:new --record
kubectl rollout pause deployment/persona-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/persona-integration
kubectl rollout pause deployment/persona-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/persona-integration
kubectl rollout status deployment/persona-integration

async function healthCheck(): Promise<{ status: string; persona: any }> {
  cons

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: PersonaClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

my-persona-project/
├── src/
│   ├── persona/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── persona/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── persona/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── persona/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── persona/
│   └── integration/
│       └── persona/
├── config/
│   ├── persona.development.json
│   ├── persona.staging.json
│   └── persona.production.json
└── docs/
    └── persona/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          Persona Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/persona/client.ts
export class PersonaService {
  private client: PersonaClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: PersonaConfig) {
    this.client = new PersonaClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('persona');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/persona/errors.ts
export class PersonaServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'PersonaServiceError';
  }

// src/persona/client.ts
import { PersonaClient } from '@persona/sdk';

let instance: PersonaClient | null = null;

export function getPersonaClient(): PersonaClient {
  if (!instance) {
    instance = new PersonaClient({
      apiKey: process.env.PERSONA_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { PersonaError } from '@persona/sdk';

async function safePersonaCall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof PersonaError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, PersonaClient>();

export function getClientForTenant(tenantId: string): PersonaClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new PersonaClient({ apiKey }));
  }
  return clients

# .env (NEVER commit to git)
PERSONA_API_KEY=sk_live_***
PERSONA_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

# 1. Generate new key in Persona dashboard
# 2. Update environment variable
export PERSONA_API_KEY="new_key_here"

# 3. Verify new key works
curl -H "Authorization: Bearer ${PERSONA_API_KEY}" \
  https://api.persona.com/health

# 4. Revoke old key in dashboard

const clients = {
  reader: new PersonaClient({
    apiKey: process.env.PERSONA_READ_KEY,
  }),
  writer: new PersonaClient({
    apiKey: process.env.PERSONA_WRITE_KEY,
  }),
};

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success' | 'failure';
  metadata?: Re

npm list @persona/sdk
npm view @persona/sdk version

open https://github.com/persona/sdk/releases

git checkout -b upgrade/persona-sdk-vX.Y.Z
npm install @persona/sdk@latest
npm test

// Before (v1.x)
import { Client } from '@persona/sdk';

// After (v2.x)
import { PersonaClient } from '@persona/sdk';

// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new PersonaClient({
  apiKey: 'xxx',
});

npm install @persona/sdk@1.x.x --save-exact

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Persona]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/persona',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-persona-signature'] as string;
    const timestamp = req.headers['x-persona-timestamp'] as string;

    if (!verifyPersonaSignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handlePersonaEvent(event);

    res.status(200).json({ received: true });
  }
);

function verifyPersonaSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.PERSONA_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

type PersonaEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface PersonaEvent {
  id: string;
  type: PersonaEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<PersonaEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handlePersonaEvent(event: PersonaEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.id}`);
  } catch (error) {
    console.error(`Failed to proc