Getting Started

Error Handling

MUDBASE uses standard HTTP status codes and structured error objects for all error responses.

Error Response Format

Every error is a flat JSON object — code is the stable, machine-matchable identifier; error and message are both human-readable (kept separate so you can show message to end users while logging error/code):

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "message": "Too many requests. Retry after the period in the Retry-After header."
}

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "message": "Too many requests. Retry after the period in the Retry-After header."
}

The HTTP status itself (not a field in the body) tells you the response category — see Error Explorer for the full list of named code values, which endpoints return each one, and the HTTP status paired with it.

SDK Error Handling

import { MudbaseError } from 'mudbase-sdk';

try {
  const result = await mudbase.collection('orders').create({ item: 'espresso' });
} catch (err) {
  if (err instanceof MudbaseError) {
    console.error(err.code);    // 'RATE_LIMITED'
    console.error(err.status);  // 429 — from the HTTP response, not the body
    console.error(err.message);

    if (err.status === 429) {
      await sleep(30_000);
    }
  }
}

import { MudbaseError } from 'mudbase-sdk';

try {
  const result = await mudbase.collection('orders').create({ item: 'espresso' });
} catch (err) {
  if (err instanceof MudbaseError) {
    console.error(err.code);    // 'RATE_LIMITED'
    console.error(err.status);  // 429 — from the HTTP response, not the body
    console.error(err.message);

    if (err.status === 429) {
      await sleep(30_000);
    }
  }
}

Last updated: August 2026