Error Handling Overview

The SnackBase SDK provides a comprehensive error handling system with typed error classes for different failure scenarios.

Overview

All SDK errors extend from the base SnackBaseError class, allowing you to catch errors generically or handle specific error types:

import {
  SnackBaseError,
  AuthenticationError,
  ValidationError,
  NetworkError,
} from "@snackbase/sdk";

try {
  const post = await client.records.create("posts", data);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Validation failed:", error.fields);
  } else if (error instanceof AuthenticationError) {
    console.error("Authentication required");
  } else if (error instanceof SnackBaseError) {
    console.error("SDK error:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}

Error Hierarchy

SnackBaseError (base class)
├── AuthenticationError (401)
├── AuthorizationError (403)
├── NotFoundError (404)
├── ConflictError (409)
├── ValidationError (422)
├── RateLimitError (429)
├── NetworkError
├── TimeoutError
└── ServerError (500+)

Error Properties

All errors include the following properties:

interface SnackBaseError {
  message: string;        // Human-readable error message
  code: string;          // Error code (e.g., "AUTHENTICATION_ERROR")
  status?: number;       // HTTP status code
  details?: any;         // Additional error details
  field?: string;        // Field name (for validation errors)
  retryable: boolean;    // Whether the request can be retried
}

Error Types

AuthenticationError (401)

Thrown when authentication fails or tokens are invalid:

try {
  await client.auth.loginWithPassword({
    email: "[email protected]",
    password: "wrong-password",
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid credentials");
    // Redirect to login
  }
}

AuthorizationError (403)

Thrown when the user lacks permission for an action:

try {
  await client.records.delete("posts", "post-id");
} catch (error) {
  if (error instanceof AuthorizationError) {
    console.error("You don't have permission to delete this post");
    // Show permission error to user
  }
}

NotFoundError (404)

Thrown when a resource is not found:

try {
  const post = await client.records.get("posts", "non-existent-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Post not found");
    // Show 404 page
  }
}

ConflictError (409)

Thrown when a resource conflict occurs (e.g., duplicate):

try {
  await client.users.create({
    email: "[email protected]",
    password: "password",
  });
} catch (error) {
  if (error instanceof ConflictError) {
    console.error("User with this email already exists");
    // Show error to user
  }
}

ValidationError (422)

Thrown when request validation fails:

try {
  await client.records.create("posts", {
    title: "",  // Required field is empty
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Validation failed:", error.fields);
    // { title: ["This field is required"] }
    // Show field-specific errors
  }
}

RateLimitError (429)

Thrown when rate limit is exceeded:

try {
  await client.records.list("posts");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error("Rate limited. Retry after:", error.retryAfter, "seconds");
    // Show rate limit message
  }
}

NetworkError

Thrown when network request fails:

try {
  await client.records.list("posts");
} catch (error) {
  if (error instanceof NetworkError) {
    console.error("Network error - please check your connection");
    // Show offline message
  }
}

TimeoutError

Thrown when request times out:

try {
  await client.records.list("posts");
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error("Request timed out");
    // Show timeout message
  }
}

ServerError (500+)

Thrown when server error occurs:

try {
  await client.records.list("posts");
} catch (error) {
  if (error instanceof ServerError) {
    console.error("Server error:", error.status);
    // Show server error message
  }
}

Global Error Handlers

Configure global error callbacks:

const client = new SnackBaseClient({
  baseUrl: "https://api.example.com",
  onAuthError: (error) => {
    console.error("Auth error:", error);
    // Redirect to login
  },
  onNetworkError: (error) => {
    console.error("Network error:", error);
    // Show offline banner
  },
  onRateLimitError: (error) => {
    console.error("Rate limited:", error.retryAfter);
    // Show rate limit message
  },
});

React Error Handling

function PostDetail({ postId }: { postId: string }) {
  const { data: post, loading, error } = useRecord("posts", postId);

  if (loading) return <div>Loading...</div>;

  if (error) {
    if (error instanceof NotFoundError) {
      return <div>Post not found</div>;
    }
    if (error instanceof ValidationError) {
      return <div>Invalid request</div>;
    }
    return <div>Error loading post</div>;
  }

  return <PostContent post={post} />;
}

Retry Logic

Check if error is retryable:

async function fetchWithRetry(collection: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.records.list(collection);
    } catch (error) {
      if (error instanceof SnackBaseError && error.retryable && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Custom Error Handler

Create a custom error handler:

async function handleApiCall<T>(
  fn: () => Promise<T>
): Promise<T | null> {
  try {
    return await fn();
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error("Validation error:", error.fields);
      showFieldErrors(error.fields);
    } else if (error instanceof AuthenticationError) {
      console.error("Authentication failed");
      redirectToLogin();
    } else if (error instanceof AuthorizationError) {
      console.error("Permission denied");
      showPermissionError();
    } else if (error instanceof NotFoundError) {
      console.error("Resource not found");
      showNotFoundError();
    } else if (error instanceof RateLimitError) {
      console.error("Rate limited:", error.retryAfter);
      showRateLimitError(error.retryAfter);
    } else if (error instanceof NetworkError) {
      console.error("Network error");
      showNetworkError();
    } else {
      console.error("Unknown error:", error);
      showGenericError();
    }
    return null;
  }
}

// Usage
const post = await handleApiCall(() =>
  client.records.get("posts", "post-id")
);

Complete Example

import {
  SnackBaseError,
  AuthenticationError,
  ValidationError,
  NetworkError,
} from "@snackbase/sdk";

async function createPost(data: PostCreate) {
  try {
    const post = await client.records.create("posts", data);
    return { success: true, data: post };
  } catch (error) {
    if (error instanceof ValidationError) {
      return {
        success: false,
        error: "Validation failed",
        fields: error.fields,
      };
    }

    if (error instanceof AuthenticationError) {
      return {
        success: false,
        error: "Please log in to create posts",
      };
    }

    if (error instanceof AuthorizationError) {
      return {
        success: false,
        error: "You don't have permission to create posts",
      };
    }

    if (error instanceof NetworkError) {
      return {
        success: false,
        error: "Network error - please check your connection",
      };
    }

    return {
      success: false,
      error: "An unexpected error occurred",
    };
  }
}

Next Steps

Error Types - Complete error type reference
Authentication - Authentication error handling
Configuration - Error callback configuration

Getting Started

Authentication

Core Services

Admin Services

Automation Services

Query Builder

Realtime

React Integration

Error Handling

Reference

Error Handling Overview

Overview

Error Hierarchy

Error Properties

Error Types

AuthenticationError (401)

AuthorizationError (403)

NotFoundError (404)

ConflictError (409)

ValidationError (422)

RateLimitError (429)

NetworkError

TimeoutError

ServerError (500+)

Global Error Handlers

React Error Handling

Retry Logic

Custom Error Handler

Complete Example

Next Steps

​Overview

​Error Hierarchy

​Error Properties

​Error Types

​AuthenticationError (401)

​AuthorizationError (403)

​NotFoundError (404)

​ConflictError (409)

​ValidationError (422)

​RateLimitError (429)

​NetworkError

​TimeoutError

​ServerError (500+)

​Global Error Handlers

​React Error Handling

​Retry Logic

​Custom Error Handler

​Complete Example

​Next Steps

Overview

Error Hierarchy

Error Properties

Error Types

AuthenticationError (401)

AuthorizationError (403)

NotFoundError (404)

ConflictError (409)

ValidationError (422)

RateLimitError (429)

NetworkError

TimeoutError

ServerError (500+)

Global Error Handlers

React Error Handling

Retry Logic

Custom Error Handler

Complete Example

Next Steps