Data Access

Errors

Understand error responses and handle failures gracefully.

Understand HTTP Status Codes

Every response includes an HTTP status code indicating the result of the request.

Code	Meaning
200	OK — request succeeded
204	No Content — delete succeeded
400	Bad Request — validation failed or malformed request
401	Unauthorized — missing or invalid credentials
403	Forbidden — insufficient permissions
404	Not Found — item or collection does not exist
500	Internal Server Error

Read the Error Response

When a request fails, the API returns a JSON body with the EngineError shape:

{
  "message": "Item not found in articles",
  "source": {
    "message": "No record matched the given key"
  },
  "meta": {
    "collection": "articles"
  }
}

Field	Type	Description
`message`	`string`	Human-readable error description
`source`	`EngineError` (optional)	Nested error providing deeper context. Chains recursively.
`meta`	`Record<string, unknown>` (optional)	Additional structured metadata about the error

The source field chains recursively — an error can contain a source that itself has a source, providing a full error chain from the outermost context down to the root cause.

Handle Errors in REST

Check response.ok before parsing the body. On failure, parse the error body to read the message and optional source chain.

fetch

const response = await fetch('https://example.monospace.io/api/blog/items/articles?fields=*', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

if (!response.ok) {
  const error = await response.json();
  console.error(`${response.status}: ${error.message}`);

  if (error.source) {
    console.error('Caused by:', error.source.message);
  }

  return;
}

const { data } = await response.json();

Handle Errors in the SDK

The SDK maps API error responses to typed error classes for structured error handling:

Class	HTTP Status	Extra Properties
`MonospaceNotFoundError`	404	`.collection`, `.key`
`MonospaceValidationError`	400	`.meta`
`MonospaceAuthError`	401	—
`MonospacePermissionError`	403	—

See Advanced — Error Handling for the complete error class reference, instanceof patterns, and source chain access.

Fix Common Errors

Use this table to diagnose the most frequent error scenarios.

Status	Context	Likely Cause
401	Any request	API key is missing, expired, or malformed
403	List items	Role lacks read permission on the collection
403	Get single item	No access to the specific item, or the item does not exist
404	Any request	Collection or endpoint does not exist
400	Create or update	Required field missing, or a validation rule failed

A 403 on a single-item request does not distinguish between "no access" and "does not exist." This is intentional — exposing whether an item exists would be a security risk.