Errors

The SDK provides two error classes — MolrooApiError for persona operations and WorldApiError for world operations. Both include a machine-readable code and HTTP status for programmatic handling.

MolrooApiError

Thrown by MolrooPersona methods and persona-related operations.

import { MolrooApiError } from '@molroo-io/sdk';

class MolrooApiError extends Error {
  message: string;
  code: string;
  status: number;
}

The name property is always 'MolrooApiError'.

Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`RATE_LIMITED`	429	Too many requests
`WORLD_NOT_FOUND`	404	World ID does not exist
`ENTITY_NOT_FOUND`	404	Entity name/ID not found in the world
`VALIDATION_ERROR`	400	Invalid request body (missing fields, wrong types)
`MUTATE_FAILED`	400	Mutation operation failed
`LLM_NOT_CONFIGURED`	400	LLM adapter required but not provided
`LLM_REQUIRED`	400	LLM adapter required when using description string for persona creation
`UNKNOWN`	varies	Unclassified server error

Example

import { MolrooApiError } from '@molroo-io/sdk';

try {
  await persona.chat('Hello');
} catch (e) {
  if (e instanceof MolrooApiError) {
    switch (e.code) {
      case 'UNAUTHORIZED':
        console.error('Check your API key');
        break;
      case 'RATE_LIMITED':
        console.error('Too many requests, retrying...');
        break;
      case 'LLM_NOT_CONFIGURED':
        console.error('Provide an LLM adapter or pass appraisal manually');
        break;
      default:
        console.error(`API error [${e.code}]: ${e.message}`);
    }
  }
}

WorldApiError

Thrown by World methods and world-related operations.

import { WorldApiError } from '@molroo-io/sdk/world';

class WorldApiError extends Error {
  message: string;
  code: string;
  status: number;
}

The name property is always 'WorldApiError'.

Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`WORLD_NOT_FOUND`	404	World ID does not exist or belongs to another tenant
`WORLD_PERSONA_NOT_FOUND`	404	Persona not found in the world
`WORLD_PERSONA_ALREADY_EXISTS`	409	Persona is already a member of the world
`ACTION_NOT_FOUND`	404	Action name not found (default or custom)
`RELATIONSHIP_NOT_FOUND`	404	Relationship ID not found
`VALIDATION_ERROR`	400	Invalid request body (missing fields, wrong types)
`UNKNOWN`	varies	Unclassified server error

Example

import { Molroo } from '@molroo-io/sdk';
import { WorldApiError } from '@molroo-io/sdk/world';

const molroo = new Molroo({ apiKey: 'mk_live_...' });

try {
  const world = await molroo.getWorld('nonexistent-id');
} catch (e) {
  if (e instanceof WorldApiError) {
    switch (e.code) {
      case 'WORLD_NOT_FOUND':
        console.error('World does not exist');
        break;
      case 'WORLD_PERSONA_NOT_FOUND':
        console.error('Add the persona to the world first');
        break;
      default:
        console.error(`API error [${e.code}]: ${e.message}`);
    }
  }
}

API Response Parsing

The SDK automatically parses API responses and unwraps the { result: T } envelope. When the API returns a non-OK HTTP status, the error response is parsed and thrown as the appropriate error class:

// API error response format:
{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity \"NonExistent\" not found in world"
  }
}

// Becomes:
MolrooApiError {
  name: 'MolrooApiError',
  message: 'Entity "NonExistent" not found in world',
  code: 'ENTITY_NOT_FOUND',
  status: 404,
}

Errors

On this page