Errors

Every error the SDK raises is one of nine exported classes, and each carries a stable code string. Branch on code, never on message, messages are human-readable text that may be reworded, while codes are contract.

import { ESPConfigError, ESPAPICallValidationError } from "@espressif/rainmaker-neo-base-sdk";

try {
  await node.setParams({ Light: { Power: true } });
} catch (error) {
  if (error instanceof ESPAPICallValidationError) {
    console.error(error.code);
  }
  throw error;
}

The classes

Class	Raised for
ESPConfigError	Invalid configuration or unconfigured SDK
ESPValidationError	Invalid input to a validated call
ESPAPICallValidationError	Arguments or state a call cannot accept
ESPTokenError	Missing or unusable tokens
ESPAuthError	Sign-up, sign-in and password failures
ESPProvError	Provisioning failures
ESPClaimError	Assisted claiming failures
ESPStorageAdapterError	Storage adaptor problems
ESPBaseError	Base class of the others

Seven extend ESPBaseError, which extends Error and adds code plus a label naming the class. ESPAuthError is the exception: it extends Error directly and adds code and originalError, which holds the underlying cause for debugging.

Catching ESPBaseError therefore catches everything except authentication errors. Catch both, or catch Error and read code defensively.

Configuration codes

ESPConfigError; thrown by configure() and by accessors on an unconfigured SDK:

SDK_NOT_CONFIGURED · INVALID_CONFIG_OBJECT · INVALID_BASE_URL · INVALID_USER_API_BASE · INVALID_REGION · INVALID_IOT_ENDPOINT · INVALID_TRANSPORT_MODE · INVALID_TRANSPORT_ORDER · INVALID_STORAGE_ADAPTER · INVALID_MQTT_ADAPTER · INVALID_PROVISION_ADAPTER

Call validation codes

ESPAPICallValidationError is the widest, covering argument checks and unreachable state. The ones worth handling explicitly:

Code	Meaning
NODE_UNREACHABLE	No transport available for the node
MISSING_NODE_REF	Parent node was garbage-collected
NODE_CONFIG_UNRESOLVED	No configuration from cache or cloud
MISSING_BASE_URL	Local transport has no known address
ADD_NODE_REQUIRES_NESTED_GROUP	addNode called on a root group
NODE_ALREADY_IN_GROUP	Node already a member
USE_LEAVE_FOR_CURRENT_USER	removeMember called with your own ID
SCHEDULE_ALREADY_EXISTS	Schedule ID already used on the node
TRIGGER_ALREADY_EXISTS	Trigger ID already used on the node
TS_PARAM_NOT_FOUND	Parameter absent from node configuration
MISSING_TS_START_TIME	Raw time-series query without startTs
MISSING_TS_CUSTOM_KEY_DATA_TYPE	key passed without dataType

Others cover missing identifiers and malformed payloads — MISSING_GROUP_ID, MISSING_NODE_ID, MISSING_USERNAME, MISSING_PARAMS, INVALID_ACTION_TARGET, INVALID_ACTION_INDEX, MISSING_AUTOMATION_NAME, INVALID_SCHEDULES, SCHEDULE_NOT_FOUND, TRIGGER_NOT_FOUND, and similar. These indicate a bug in the calling code rather than a runtime condition to recover from.

Authentication and token codes

ESPAuthError: LOGIN_FAILED · LOGIN_FAILED_MISSING_TOKENS · NOT_LOGGED_IN · SIGNUP_FAILED · CONFIRM_SIGNUP_FAILED · FORGOT_PASSWORD_FAILED · PASSWORD_RESET_FAILED · CHANGE_PASSWORD_FAILED · GET_LOGGED_IN_USER_FAILED · TOKEN_REFRESH_FAILED_MISSING_TOKENS

ESPTokenError: MISSING_ACCESS_TOKEN · MISSING_ID_TOKEN · MISSING_REFRESH_TOKEN · EXTEND_SESSION_FAILED

Wrong credentials and unknown accounts look the same

Both surface as LOGIN_FAILED, deliberately; the deployment does not reveal whether an account exists. Present a single "check your details" message rather than trying to distinguish them.

ESPAuthError also carries originalError. Log it, but do not branch on its shape; it is whatever the underlying client threw.

Provisioning codes

ESPProvError: MISSING_PROV_ADAPTER · INVALID_PROVISION_TYPE · MISSING_NODE_ID · MISSING_ID_TOKEN · FAILED_PROV · FAILED_USER_DEVICE_ASSOCIATION · FAILED_USER_NODE_MAPPING_REQUEST_CREATION · FAILED_USER_NODE_MAPPING_CLOUD_TIMEOUT · FAILED_CHALLENGE_RESPONSE · DEVICE_CHALLENGE_RESPONSE_FAILED · INVALID_CHALLENGE_RESPONSE_FORMAT · INVALID_MAPPING_RESPONSE · VERIFY_NODE_MAPPING_FAILED · SET_NETWORK_CREDENTIALS_FAILED · NODE_ONLINE_TIMEOUT

NODE_ONLINE_TIMEOUT is the one to expect in normal use; it means waitForOnline gave up, not that provisioning failed. The node has its credentials and may come online later.

Claiming codes

ESPClaimError: CLAIM_START_FAILED · CLAIM_ABORTED · CLAIM_API_FAILED · CLAIM_API_NOT_CONFIGURED · DEVICE_MAC_UNAVAILABLE · CSR_RETRIEVAL_FAILED · CSR_STALLED · CERTIFICATE_SEND_FAILED

This class appends the claiming service's own reason to the message in parentheses. Those reasons are actionable, so surface the message rather than replacing it. See Assisted claiming.

Storage and validation codes

ESPStorageAdapterError: UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API; the built-in fallback was used on a runtime with no localStorage. Supply a storage adaptor.

ESPValidationError: MISSING_LOGIN_PASSWORD.

Errors the SDK does not wrap

Not every failure becomes a typed error. Transport and HTTP failures propagate from the underlying layer, so a network error from a REST call arrives as whatever the runtime threw. Treat an unrecognised error as retryable infrastructure trouble, and a typed one as a specific, described condition.

Related

• Configuration reference — what triggers config errors
• Provisioning — where provisioning errors arise
• Device control — NODE_UNREACHABLE in context
• Authentication — the auth failure paths
• Constants and enums — the exported code objects