Error Handling

​

Overview

At Formbricks, we follow consistent error handling patterns to ensure reliability, debuggability, and maintainability across our codebase. This document outlines our standard approaches to error handling.

​

Core Principles

1. Type Safety: Use typed errors and results
2. Meaningful Messages: Provide clear, actionable error messages
3. Proper Propagation: Handle or propagate errors appropriately
4. Logging: Ensure errors are properly logged for debugging
5. Recovery: Implement graceful fallbacks where possible

​

Standard Error Types

We maintain a set of standardized error types for different scenarios:

export interface ApiErrorResponse {
code:
| "not_found"
| "gone"
| "bad_request"
| "internal_server_error"
| "unauthorized"
| "method_not_allowed"
| "not_authenticated"
| "forbidden"
| "network_error";
message: string;
status: number;
url: URL;
details?: Record<string, string | string[] | number | number[] | boolean | boolean[]>;
responseMessage?: string;
}

​

Error Handling Patterns

​

API Error Handling

For API endpoints:

export const GET = async (request: Request) => {
try {
const authentication = await authenticateRequest(request);
if (!authentication) return responses.notAuthenticatedResponse();
const data = await fetchData(authentication.environmentId!);
return responses.successResponse(data);
} catch (error) {
if (error instanceof DatabaseError) {
return responses.badRequestResponse(error.message);
}
throw error;
}
};

​

Client-Side Error Handling

For client-side operations:

const handleOperation = async () => {
const result = await performAction();
if (!result.ok) {
logger.error(`Operation failed: ${result.error.message}`);
toast.error("Operation failed. Please try again.");
return;
}
// Process successful result
processResult(result.data);
};

​

Best Practices

1. Never Swallow Errors

   • Always handle or propagate errors
   • Log errors appropriately for debugging
   • Use error boundaries in React components

2. Type Safety

   • Use typed error responses
   • Leverage TypeScript for compile-time error checking
   • Define clear error interfaces

3. Error Messages

   • Include relevant context in error messages
   • Make messages actionable for developers
   • Use consistent error formatting

4. Error Recovery

   • Implement fallback behaviors where appropriate
   • Gracefully degrade functionality when possible
   • Provide user feedback for recoverable errors

5. Documentation

   • Document expected errors in function JSDoc
   • Include error handling in code examples
   • Keep error handling documentation up to date

​

Testing Error Scenarios

Always include error case testing:

describe("fetchEnvironmentState()", () => {
test("returns err(...) on network error", async () => {
const mockNetworkError = {
code: "network_error",
message: "Timeout",
responseMessage: "Network fail",
};
const result = await fetchEnvironmentState();
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.error.code).toBe(mockNetworkError.code);
expect(result.error.message).toBe(mockNetworkError.message);
}
});
});

These standards ensure consistent, reliable error handling across the Formbricks codebase while maintaining good developer experience and system reliability.