Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.larksh.com/llms.txt

Use this file to discover all available pages before exploring further.

LarkError extends the native Error class with a code property for programmatic error handling. All errors thrown or surfaced by the Lark SDK are instances of LarkError. 
import { LarkError } from '@lark-sh/client';

try {
  await db.ref('secret/data').get();
} catch (error) {
  if (error instanceof LarkError) {
    console.error(`[${error.code}] ${error.message}`);
  }
}

​
Properties

PropertyTypeDescription
codestringA machine-readable error code identifying the type of error.
messagestringA human-readable description of the error.

​
Error Codes

CodeDescription
permission_deniedThe client does not have permission to perform the requested operation. Check your security rules.
invalid_dataThe data provided is invalid or cannot be stored (e.g., contains unsupported types or exceeds size limits).
not_foundThe requested resource does not exist.
invalid_pathThe specified path is malformed or contains illegal characters.
timeoutThe operation timed out before completing. This can occur during reads, writes, or connection attempts.
not_connectedThe operation requires an active connection, but the client is not connected to the server.
condition_failedA transaction or conditional write failed because the underlying data was modified by another client.
max_retries_exceededA transaction exceeded the maximum number of retry attempts without successfully committing.
write_taintedA pending write was invalidated because it conflicts with a server-side change.
view_recoveringThe local view of the data is temporarily inconsistent and is being recovered. Retry the operation shortly.
auth_requiredThe operation requires authentication, but the client is not signed in. Call signIn() first.

​
Handling Errors

​
With try/catch

try {
  await db.ref('protected/path').set({ key: 'value' });
} catch (error) {
  if (error instanceof LarkError) {
    switch (error.code) {
      case 'permission_denied':
        console.error('Access denied. Please sign in.');
        break;
      case 'not_connected':
        console.error('No connection. Retrying when online.');
        break;
      default:
        console.error(`Unexpected error: ${error.code}`);
    }
  }
}

​
With the error event

Connection-level errors are emitted via the onError event on the LarkDatabase instance. 
db.onError((error: LarkError) => {
  console.error(`Connection error [${error.code}]: ${error.message}`);
});
Transaction-related codes (condition_failed, max_retries_exceeded, write_tainted) indicate that the transaction could not commit. In most cases the SDK retries automatically, but if max_retries_exceeded is thrown, you may need to retry with different logic.