Error Handling

Handle errors that may occur during SDK operations.

Error Types

import { Pinner, PinnerError } from "@lumeweb/pinner";
 
const pinner = new Pinner({ jwt: "YOUR_API_TOKEN" });
 
try {
  const result = await pinner.upload(file);
} catch (error) {
  if (error instanceof PinnerError) {
    console.error("Code:", error.code);
    console.error("Message:", error.message);
    console.error("Retryable:", error.retryable);
    console.error("Cause:", error.cause);
  }
}

Error Properties

All PinnerError instances include:

Property	Type	Description
`code`	`string`	Unique error code for programmatic handling
`message`	`string`	Human-readable error description
`retryable`	`boolean`	Whether the operation can be retried
`cause`	`Error	undefined`
`name`	`string`	Error class name

Error Classes

Error Class	Code	Retryable	Description
`PinnerError`	Various	Varies	Base error class for all Pinner errors
`ConfigurationError`	`CONFIGURATION_ERROR`	No	Invalid SDK configuration
`AuthenticationError`	`AUTHENTICATION_ERROR`	No	Invalid or expired API token
`UploadError`	`UPLOAD_ERROR`	Varies	Base class for upload errors
`NetworkError`	`NETWORK_ERROR`	Yes	Network connectivity issue
`ValidationError`	`VALIDATION_ERROR`	No	Invalid input or validation failure
`EmptyFileError`	`EMPTY_FILE_ERROR`	No	Attempted to upload empty file
`TimeoutError`	`TIMEOUT_ERROR`	Yes	Request timed out
`PinError`	`PIN_ERROR`	Varies	Pin operation failed
`NotFoundError`	`NOT_FOUND`	No	Content not found
`RateLimitError`	`RATE_LIMIT_EXCEEDED`	Yes	Too many requests
`EnvironmentError`	`ENVIRONMENT_ERROR`	No	Unsupported environment (e.g., missing required APIs)

RateLimitError Properties

try {
  await pinner.upload(file);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error("Rate limited, retry after:", error.retryAfter, "seconds");
  }
}

Common Error Codes

Code	Description
`CONFIGURATION_ERROR`	Invalid SDK configuration
`AUTHENTICATION_ERROR`	Invalid or expired API token
`UPLOAD_ERROR`	Upload failed
`NETWORK_ERROR`	Network connectivity issue
`VALIDATION_ERROR`	Invalid input or validation failure
`EMPTY_FILE_ERROR`	Cannot upload empty file
`TIMEOUT_ERROR`	Request timed out
`PIN_ERROR`	Pin operation failed
`NOT_FOUND`	Content not found
`RATE_LIMIT_EXCEEDED`	Too many requests
`ENVIRONMENT_ERROR`	Unsupported environment

Retry Strategies

import { Pinner, isRetryable } from "@lumeweb/pinner";
 
async function uploadWithRetry(file, maxRetries = 3) {
  let lastError;
 
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await pinner.upload(file);
    } catch (error) {
      lastError = error;
 
      if (!isRetryable(error)) {
        throw error;
      }
 
      console.log(`Retry attempt ${attempt}/${maxRetries}`);
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }
 
  throw lastError;
}

Handling Network Errors

import { Pinner, NetworkError } from "@lumeweb/pinner";
 
const pinner = new Pinner({ jwt: "YOUR_API_TOKEN" });
 
try {
  const result = await pinner.upload(file);
} catch (error) {
  if (error instanceof NetworkError) {
    console.error("Network error. Check your connection.");
    return;
  }
  throw error;
}