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

Type Safety: Use typed errors and results
Meaningful Messages: Provide clear, actionable error messages
Proper Propagation: Handle or propagate errors appropriately
Logging: Ensure errors are properly logged for debugging
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.workspaceId!);
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

Never Swallow Errors
- Always handle or propagate errors
- Log errors appropriately for debugging
- Use error boundaries in React components
Type Safety
- Use typed error responses
- Leverage TypeScript for compile-time error checking
- Define clear error interfaces
Error Messages
- Include relevant context in error messages
- Make messages actionable for developers
- Use consistent error formatting
Error Recovery
- Implement fallback behaviors where appropriate
- Gracefully degrade functionality when possible
- Provide user feedback for recoverable errors
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.

Development

Local Setup

Technical Handbook

Standards

Contributions

Guides

Support

Overview

Core Principles

Standard Error Types

Error Handling Patterns

API Error Handling

Client-Side Error Handling

Best Practices

Testing Error Scenarios

​Overview

​Core Principles

​Standard Error Types

​Error Handling Patterns

​API Error Handling

​Client-Side Error Handling

​Best Practices

​Testing Error Scenarios

Overview

Core Principles

Standard Error Types

Error Handling Patterns

API Error Handling

Client-Side Error Handling

Best Practices

Testing Error Scenarios