Errors

The SDK throws MolrooApiError for all API errors and adapter-related errors. Each error includes a machine-readable code and HTTP status for programmatic handling.

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

MolrooApiError

class MolrooApiError extends Error {
  /** Human-readable error message */
  message: string;

  /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND') */
  code: string;

  /** HTTP status code */
  status: number;

  constructor(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 (used by convenience methods like `addEntity`, `removeEntity`)
`LLM_NOT_CONFIGURED`	400	LLM adapter required but not provided (call `chat()` without adapter or appraisal)
`STORAGE_NOT_FOUND`	404	Snapshot not found at the specified storage key
`STORAGE_NOT_CONFIGURED`	400	Storage adapter required but not provided (call `saveSnapshotToStorage` or `loadSnapshotFromStorage`)
`UNKNOWN`	varies	Unclassified server error

Error Handling

Basic try/catch

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

try {
  await world.chat('NonExistent', 'Hello');
} catch (e) {
  if (e instanceof MolrooApiError) {
    console.log(e.code);    // 'ENTITY_NOT_FOUND'
    console.log(e.status);  // 404
    console.log(e.message); // 'Entity "NonExistent" not found'
  }
}

Handling specific error codes

try {
  const result = await world.chat('Sera', 'Hello');
} catch (e) {
  if (!(e instanceof MolrooApiError)) throw e;

  switch (e.code) {
    case 'UNAUTHORIZED':
      console.error('Check your API key');
      break;
    case 'RATE_LIMITED':
      console.error('Too many requests, retrying in 1s...');
      await new Promise(r => setTimeout(r, 1000));
      break;
    case 'ENTITY_NOT_FOUND':
      console.error(`Entity not found: ${e.message}`);
      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}`);
  }
}

LLM not configured

This error is thrown when you call chat() without an LLM adapter and without providing options.appraisal:

// No LLM adapter configured
const world = await MolrooWorld.create(
  { baseUrl: 'https://api.molroo.io', apiKey: 'key' },
  { /* setup */ },
);

try {
  await world.chat('Sera', 'Hello');
} catch (e) {
  // MolrooApiError: LLM adapter is required for this operation.
  // Provide llm option, or pass appraisal directly.
  console.log(e.code); // 'LLM_NOT_CONFIGURED'
}

// Fix: provide appraisal manually
await world.chat('Sera', 'Hello', {
  appraisal: {
    goal_relevance: 0.5,
    goal_congruence: 0.5,
    expectedness: 0.5,
    controllability: 0.5,
    agency: 0,
    norm_compatibility: 0.5,
  },
});

Storage not configured

try {
  await world.saveSnapshotToStorage();
} catch (e) {
  // MolrooApiError: Storage adapter is required for this operation.
  console.log(e.code); // 'STORAGE_NOT_CONFIGURED'
}

Convenience methods (addEntity, removeEntity, moveEntity, addSpace, setRelationship, updateEnvironment) throw MolrooApiError with code MUTATE_FAILED when the underlying mutation operation fails:

try {
  await world.addEntity({ name: 'Sera' }); // duplicate name
} catch (e) {
  console.log(e.code); // 'MUTATE_FAILED'
}

When using mutate() directly, individual operation failures are reported in the result without throwing:

const result = await world.mutate([
  { op: 'remove_entity', target: 'nonexistent' },
]);

console.log(result.results[0].ok);    // false
console.log(result.results[0].error); // 'Entity not found'

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 MolrooApiError:

// 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

Errors

MolrooApiError

Error Codes

Error Handling

Basic try/catch

Handling specific error codes

LLM not configured

Storage not configured

Mutation errors

API Response Parsing

On this page