Error Handling

The SDK turns HTTP failures and network issues into typed errors. All extend NomaError, which includes optional HTTP status, API error code, details, and requestInfo for debugging.

`NomaError`

Base class for every SDK error.

Property	Type	Description
`message`	`string`	Human-readable message (from API or fallback).
`name`	`string`	Error class name.
`statusCode`	`number \| undefined`	HTTP status when the failure came from a response.
`code`	`string \| undefined`	Application error code when the API returns one.
`details`	`unknown`	Validation errors, nested messages, or extra fields.
`requestInfo`	`object \| undefined`	Safe summary of the request (method, URL, params, redacted body).

Typed error classes

Class	Default HTTP	When it happens
`AuthenticationError`	401	Invalid or missing API key or user token.
`AuthorizationError`	403	Token valid but not allowed to perform the action.
`NotFoundError`	404	Resource missing (collection, entry, asset, and so on).
`ValidationError`	422	Invalid payload or client configuration.
`RateLimitError`	429	Too many requests.
`ServerError`	500, 502, 503, 504	Server-side failure.
`NetworkError`	undefined	No HTTP response (DNS, refused connection, and similar).
`TimeoutError`	undefined	Request exceeded the client timeout.

Unknown status codes still become NomaError with statusCode set.

Example: narrow errors in `try/catch`

import {
  createClient,
  AuthenticationError,
  NotFoundError,
  ValidationError,
} from "@nomacms/js-sdk"
 
const noma = createClient({ projectId, apiKey })
 
try {
  await noma.content.get("posts", postId)
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Rotate or reload API key
    return
  }
  if (error instanceof NotFoundError) {
    // Show 404 UI
    return
  }
  if (error instanceof ValidationError) {
    console.error(error.details)
    return
  }
  throw error
}

`requestInfo`

On errors thrown from the generic HTTP client, requestInfo contains:

method - HTTP verb
url - Full URL (without exposing secrets in the path)
params - Query object
data - Request body with passwords and tokens redacted on /auth/* routes

Use it for logs and support tickets instead of logging raw fetch options.

Auth-specific details

For auth responses, the SDK may attach verification_token, verification_required, or related fields to details when email verification is required. Handle these in your sign-up flow per Project Auth.

Configuration errors

Invalid createClient options (for example missing projectId) throw ValidationError before any network call.

Installation & Setup - timeout and getDebugInfo.
Content - Common validation failures on create and update.

Error Handling

Error Handling

Typed error classes

Auth-specific details

Configuration errors

Related

Search documentation