Matilda
Contact
Client SDK · Reference

Error handling.

Typed error classes, chat error codes, and the SSE stall watchdog.

MatildaAPIError

Thrown on non-2xx HTTP responses from the API.

TypeScript
class MatildaAPIError extends Error {
  readonly status: number;       // HTTP status code
  readonly responseText: string; // Raw response body
}

SafetyReplaceError

Thrown by chat.streamText(), chat.streamObject(), and chat.createObject() when the server replaces the output via a safety filter. The message property contains the replacement text (or empty string), and categories lists the safety categories that triggered the replacement.

TypeScript
class SafetyReplaceError extends Error {
  readonly categories: string[];
}

MatildaObjectParseError

Thrown by chat.streamObject() and chat.createObject() when the response cannot be parsed as JSON or fails zod validation — e.g. when a stream is truncated. raw contains the full response text; cause is the underlying JSON.parse or zod error. See Structured output.

TypeScript
class MatildaObjectParseError extends Error {
  readonly raw: string;
  readonly cause: unknown;
}

AuthError

Thrown by auth flows. The code field is an OAuth error code (e.g. 'invalid_grant', 'authorization_pending', 'expired_token', 'access_denied'). The retryable field distinguishes transient failures (5xx, network) from permanent ones (revoked refresh token).

TypeScript
class AuthError extends Error {
  readonly code: string;
  readonly retryable: boolean;
}

Chat error codes (ChatErrorCode)

These codes are emitted via the response.error stream event and appear in MatildaChatResponse.errors:

CodeDescription
internal_errorServer-side failure.
upstream_unavailableThe AI model is not responding.
rate_limitedToo many requests.
content_blockedSafety filter blocked the content.
stream_abortedThe stream was interrupted before completion.
deadline_exceededThe response did not finish before the deadline.
context_too_largeThe conversation is too long for the model.
stalledNo SSE events for the configured stall window.
stream_expiredThe durable stream buffer expired (resume path only).
unknownUnclassified error (old server without typed codes).

Stall watchdog

The streaming parser arms an idle-event watchdog. If no SSE event arrives for stallTimeoutMs milliseconds, the stream is considered dead and aborted with a 'stalled' error.

  • Default: 45_000 ms (3× the server's 15-second keep-alive ping cadence)
  • Disable: Pass stallTimeoutMs: 0 in MatildaRequestOptions (not recommended — mobile loses background-to-foreground hung-stream recovery)

Error handling example

TypeScript
import Matilda, { MatildaAPIError, SafetyReplaceError } from '@maincode-ai/matilda-client-sdk';

try {
  const text = await client.chat.createText({ input: 'Hello!' });
  console.log(text);
} catch (err) {
  if (err instanceof MatildaAPIError) {
    if (err.status === 401) {
      console.error('Session expired — re-authenticate.');
    } else if (err.status === 429) {
      console.error('Rate limited — slow down.');
    } else {
      console.error(`API error ${err.status}: ${err.responseText}`);
    }
  } else if (err instanceof SafetyReplaceError) {
    console.error(`Safety filter: ${err.categories.join(', ')}`);
  } else {
    console.error('Unexpected error:', err);
  }
}