Errors & Error Handling

import {
  PersonaApiError,
  PersonaAuthError,
  PersonaValidationError,
} from '@personaai/sdk';

​

Error class hierarchy

Error
└── PersonaApiError            (base — any non-2xx / {success:false} response)
    ├── PersonaAuthError       (401, 403)
    └── PersonaValidationError (400)

​

PersonaApiError

class PersonaApiError extends Error {
  readonly statusCode: number;   // HTTP status, e.g. 404
  readonly code: string;         // machine-readable error code, e.g. 'NOT_FOUND'
  readonly response: unknown;    // the parsed error body (the envelope object), if any
}

• message — the human-readable string from the envelope (inherited from Error). Safe to log.
• code — mirrors the backend’s machine-readable code (e.g. VALIDATION_ERROR, UNAUTHORIZED, PROJECT_NOT_ACTIVE, NOT_FOUND, EXTERNAL_USER_REQUIRED). Falls back to UNKNOWN_ERROR when the response body carries no code.
• response — the raw parsed error body ({success:false, message, code, ...}), useful for debugging. May be undefined for non-JSON error responses.

​

PersonaAuthError

​

PersonaValidationError

​

Handling errors

import {
  PersonaApiError,
  PersonaAuthError,
  PersonaValidationError,
} from '@personaai/sdk';

try {
  await persona.agents.create({
    name: '',
    systemPrompt: '...',
    providerId: '...',
  });
} catch (err) {
  if (err instanceof PersonaValidationError) {
    console.error(`Bad request (${err.code}): ${err.message}`);
  } else if (err instanceof PersonaAuthError) {
    console.error(`Auth problem (${err.statusCode}): ${err.message}`);
  } else if (err instanceof PersonaApiError) {
    console.error(`API error (${err.statusCode}/${err.code}): ${err.message}`);
  } else {
    // Not a Persona error — a network failure, abort, JSON parse error, etc.
    throw err;
  }
}

​

What causes each error

​

Common failure scenarios

​

Authentication / authorization failures

• Wrong or revoked credential → 401 PersonaAuthError. Verify PERSONA_CREDENTIAL and re-mint via Studio if needed.
• Project suspended / not active → 403 PersonaAuthError with PROJECT_NOT_ACTIVE.
• Cross-identity access: a runtime-plane client (with externalUserId) calling control-plane resources like Providers → 404 (existence-hiding) or empty lists, not a loud auth error. Providers can never be owned by an external user.

​

EXTERNAL_USER_REQUIRED (400)

​

Validation failures (400)

• Missing required fields (name, systemPrompt, providerId on Agent create, etc.).
• contextOverride longer than 4000 chars → 400 INVALID_CONTEXT_OVERRIDE (rejected, not truncated).
• bulkDelete with more than 100 ids → 400 before anything is deleted.
• Uploading more than 10 files or a file over 20MB to a Knowledge base → 400.
• Unsupported upload file types (not PDF/TXT/MD/JSON/CSV) → 400.
• scope: 'mine' on a control-plane client (no externalUserId) → the server rejects it.

​

Not found / ownership (404)

• get()/update()/delete() on an id the credential’s scope doesn’t own → 404 PersonaApiError. The API deliberately does not distinguish “doesn’t exist” from “not authorized” (existence-hiding).
• chat.stream() with a threadId that doesn’t belong to the asserted user + agent → 404. It does not silently fall back to a different conversation.

​

Network / API failures

• DNS/TCP failures, timeouts, and aborted requests throw the runtime’s own network errors (e.g. TypeError: fetch failed) — not PersonaApiError. Wrap accordingly, and don’t typecheck only against the Persona classes.
• 429 rate limits are retried automatically; only after maxRetries is exhausted does a PersonaApiError with statusCode: 429 surface.

​

Errors that are NOT thrown

• bulkDelete() partial failures do not throw — partial failures land in the result’s failed array. Check it.
• testConnection() on Providers/MCPs returns { success: false, message } for a reachable endpoint that rejects the credentials — that’s a result, not a thrown error. A genuinely unreachable endpoint throws.
• Structured chat run failures (provider auth, tool timeout, context length exceeded) are not thrown by chat.sendMessage() — they’re returned as result.error (a PersonaRunErrorEvent). See Chat.