Error Handling

All molroo-api errors follow a consistent JSON format. This guide covers every error code, what causes it, and how to handle it -- including WebSocket-specific errors.

Error Response Format

Every REST error response has this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "status": 400,
    "message": "Human-readable description of what went wrong"
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code (use this in code)
`status`	`number`	HTTP status code
`message`	`string`	Human-readable explanation

Error Codes

Authentication Errors

Code	Status	Description	Fix
`UNAUTHORIZED`	401	Missing or invalid API key	Check `Authorization: Bearer <key>` header
`FORBIDDEN`	403	API key lacks permission for this action	Verify key permissions in Dashboard

Validation Errors

Code	Status	Description	Fix
`VALIDATION_ERROR`	400	Request body failed validation	Check field types, required fields, ranges
`INVALID_PERSONA`	400	Personality traits out of `[0, 1]` range	Ensure all HEXACO values are between 0-1
`INVALID_APPRAISAL`	400	Appraisal vector values out of valid ranges	Check ranges: goal_relevance `[0,1]`, goal_congruence `[-1,1]`, etc.
`INVALID_VAD`	400	VAD values out of range	V: `[-1,1]`, A: `[0,1]`, D: `[-1,1]`
`INVALID_PRESET`	400	Unknown preset name	Use a valid preset: `companion`, `mentor`, `rival`, `stoic`, `creative`, `professional`

Resource Errors

Code	Status	Description	Fix
`NOT_FOUND`	404	Persona, session, or resource not found	Verify the ID exists and belongs to your account

Rate Limiting

Code	Status	Description	Fix
`RATE_LIMIT`	429	Too many requests	Back off and retry with exponential delay

The 429 response includes a Retry-After header indicating how many seconds to wait.

Server Errors

Code	Status	Description	Fix
`INTERNAL_ERROR`	500	Unexpected server error	Retry after a short delay; contact support if persistent
`SERVICE_UNAVAILABLE`	503	API is temporarily unavailable	Check status page; retry later

Handling Errors in Code

JavaScript

async function callMolroo(url, options) {
  const response = await fetch(url, options);
 
  if (!response.ok) {
    const { error } = await response.json();
 
    switch (error.code) {
      case "UNAUTHORIZED":
        throw new Error("Invalid API key. Check your credentials.");
      case "RATE_LIMIT":
        const retryAfter = response.headers.get("Retry-After") || 5;
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return callMolroo(url, options); // retry
      case "NOT_FOUND":
        throw new Error(`Resource not found: ${error.message}`);
      case "VALIDATION_ERROR":
        throw new Error(`Bad request: ${error.message}`);
      default:
        throw new Error(`API error [${error.code}]: ${error.message}`);
    }
  }
 
  return response.json();
}

Python

import time
import requests
 
def call_molroo(method, url, **kwargs):
    response = getattr(requests, method)(url, **kwargs)
 
    if response.ok:
        return response.json()
 
    error = response.json().get("error", {})
    code = error.get("code", "UNKNOWN")
    message = error.get("message", "Unknown error")
 
    if code == "RATE_LIMIT":
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return call_molroo(method, url, **kwargs)
 
    if code == "UNAUTHORIZED":
        raise PermissionError(f"Invalid API key: {message}")
 
    if code == "NOT_FOUND":
        raise LookupError(f"Resource not found: {message}")
 
    if code == "VALIDATION_ERROR":
        raise ValueError(f"Validation failed: {message}")
 
    raise RuntimeError(f"API error [{code}]: {message}")

WebSocket Error Handling

WebSocket connections have their own error patterns. Errors are sent as JSON messages with type: "error":

{
  "type": "error",
  "code": "INVALID_MESSAGE",
  "message": "Unknown message type: foo"
}

WebSocket Error Codes

Code	Description	Fix
`INVALID_MESSAGE`	Malformed JSON or unknown message type	Check message format and `type` field
`UNAUTHORIZED`	Invalid or expired token in connection URL	Reconnect with a valid API key
`SESSION_NOT_FOUND`	Session ID does not exist	Verify session ID or create a new session
`RATE_LIMIT`	Too many messages sent	Throttle message frequency

Handling WebSocket Errors

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
 
  if (msg.type === "error") {
    console.error(`WebSocket error [${msg.code}]: ${msg.message}`);
 
    switch (msg.code) {
      case "UNAUTHORIZED":
        // Token expired or invalid — reconnect with fresh token
        ws.close();
        reconnectWithNewToken();
        break;
      case "INVALID_MESSAGE":
        // Fix the message format and retry
        console.error("Check your message format");
        break;
      case "RATE_LIMIT":
        // Slow down message frequency
        throttleMessages();
        break;
    }
    return;
  }
 
  // Handle normal messages...
};

Connection Drop Recovery

WebSocket connections can close unexpectedly. Always implement reconnection logic:

ws.onclose = (event) => {
  if (event.code === 1000) {
    // Normal close — do nothing
    return;
  }
 
  // Abnormal close — reconnect
  console.log(`Connection lost (code: ${event.code}). Reconnecting...`);
  reconnectWithBackoff();
};
 
ws.onerror = (error) => {
  console.error("WebSocket error:", error);
  // The onclose handler will fire after this — reconnection happens there
};

Common WebSocket close codes:

Code	Meaning	Action
`1000`	Normal closure	None
`1001`	Server going away (restart)	Reconnect after short delay
`1006`	Abnormal closure (no close frame)	Reconnect with backoff
`1008`	Policy violation	Check your API key and usage
`1011`	Server error	Reconnect with backoff

Retry Strategy

For transient errors (429, 500, 503), use exponential backoff:

async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === maxRetries) throw err;
 
      const delay = Math.min(1000 * 2 ** attempt, 30000);
      const jitter = delay * (0.5 + Math.random() * 0.5);
      await new Promise((r) => setTimeout(r, jitter));
    }
  }
}
 
// Usage
const result = await withRetry(() =>
  callMolroo("https://api.molroo.io/v1/turn", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  })
);

Common Mistakes

Mistake	Error Code	Solution
Missing `Content-Type` header	`VALIDATION_ERROR`	Add `Content-Type: application/json`
Personality trait > 1 or < 0	`INVALID_PERSONA`	Keep all HEXACO values in `[0, 1]`
Using deleted session ID	`NOT_FOUND`	Create a new session
Sending `goal_congruence: 2.0`	`INVALID_APPRAISAL`	Valid range is `[-1, 1]`
Invalid preset name	`INVALID_PRESET`	Check available presets in Persona Design
Sending non-JSON over WebSocket	`INVALID_MESSAGE`	Always `JSON.stringify()` before sending
Using test key (`mk_test_`) in production	--	Switch to `mk_live_` key

Error Handling

On this page