Comprehensive HTTP-based error classes providing consistent error handling across all transport methods and operations with proper HTTP status code mapping and structured error information.
Core error class that all FeathersJS errors extend, providing JSON serialization and consistent error structure.
/**
* Base FeathersJS error class with HTTP status code and JSON serialization
*/
class FeathersError extends Error {
/** Error name/type */
name: string;
/** Error message */
message: string;
/** HTTP status code */
code: number;
/** Error class name */
className: string;
/** Additional error data */
data?: any;
/** Validation errors or nested errors */
errors?: any;
/** Convert error to JSON representation */
toJSON(): FeathersErrorJSON;
}
interface FeathersErrorJSON {
name: string;
message: string;
code: number;
className: string;
data?: any;
errors?: any;
}Usage Examples:
import { errors } from "@feathersjs/client";
try {
const user = await userService.get("invalid-id");
} catch (error) {
if (error instanceof errors.FeathersError) {
console.log("Error code:", error.code);
console.log("Error name:", error.name);
console.log("Error message:", error.message);
console.log("Error data:", error.data);
// Serialize to JSON
const errorJSON = error.toJSON();
console.log("JSON:", errorJSON);
}
}HTTP client error classes for requests that cannot be processed due to client-side issues.
/**
* 400 Bad Request - Invalid request syntax or parameters
*/
class BadRequest extends FeathersError {
code: 400;
className: "bad-request";
}
/**
* 401 Unauthorized - Authentication required or failed
*/
class NotAuthenticated extends FeathersError {
code: 401;
className: "not-authenticated";
}
/**
* 402 Payment Required - Payment required to access resource
*/
class PaymentError extends FeathersError {
code: 402;
className: "payment-error";
}
/**
* 403 Forbidden - Access denied with valid authentication
*/
class Forbidden extends FeathersError {
code: 403;
className: "forbidden";
}
/**
* 404 Not Found - Resource does not exist
*/
class NotFound extends FeathersError {
code: 404;
className: "not-found";
}
/**
* 405 Method Not Allowed - HTTP method not supported for resource
*/
class MethodNotAllowed extends FeathersError {
code: 405;
className: "method-not-allowed";
}
/**
* 406 Not Acceptable - Server cannot produce requested content type
*/
class NotAcceptable extends FeathersError {
code: 406;
className: "not-acceptable";
}
/**
* 408 Request Timeout - Request took too long to complete
*/
class Timeout extends FeathersError {
code: 408;
className: "timeout";
}
/**
* 409 Conflict - Request conflicts with current resource state
*/
class Conflict extends FeathersError {
code: 409;
className: "conflict";
}
/**
* 410 Gone - Resource no longer available
*/
class Gone extends FeathersError {
code: 410;
className: "gone";
}
/**
* 411 Length Required - Content-Length header required
*/
class LengthRequired extends FeathersError {
code: 411;
className: "length-required";
}
/**
* 422 Unprocessable Entity - Request well-formed but semantically invalid
*/
class Unprocessable extends FeathersError {
code: 422;
className: "unprocessable";
}
/**
* 429 Too Many Requests - Rate limit exceeded
*/
class TooManyRequests extends FeathersError {
code: 429;
className: "too-many-requests";
}Usage Examples:
import { errors } from "@feathersjs/client";
// Handle specific client errors
try {
const result = await userService.create(invalidData);
} catch (error) {
if (error instanceof errors.BadRequest) {
console.log("Invalid data provided:", error.data);
showValidationErrors(error.errors);
} else if (error instanceof errors.NotAuthenticated) {
console.log("Please log in to continue");
redirectToLogin();
} else if (error instanceof errors.Forbidden) {
console.log("Access denied");
showAccessDeniedMessage();
} else if (error instanceof errors.NotFound) {
console.log("Resource not found");
show404Page();
} else if (error instanceof errors.Conflict) {
console.log("Resource already exists or conflict occurred");
handleConflict(error);
} else if (error instanceof errors.Unprocessable) {
console.log("Validation failed:", error.errors);
showValidationErrors(error.errors);
} else if (error instanceof errors.TooManyRequests) {
console.log("Rate limit exceeded, please try again later");
showRateLimitMessage();
}
}HTTP server error classes for issues that occur on the server side.
/**
* 500 Internal Server Error - Generic server error
*/
class GeneralError extends FeathersError {
code: 500;
className: "general-error";
}
/**
* 501 Not Implemented - Server does not support requested functionality
*/
class NotImplemented extends FeathersError {
code: 501;
className: "not-implemented";
}
/**
* 502 Bad Gateway - Invalid response from upstream server
*/
class BadGateway extends FeathersError {
code: 502;
className: "bad-gateway";
}
/**
* 503 Service Unavailable - Server temporarily unavailable
*/
class Unavailable extends FeathersError {
code: 503;
className: "unavailable";
}Usage Examples:
// Handle server errors
try {
const result = await userService.find();
} catch (error) {
if (error instanceof errors.GeneralError) {
console.log("Server error occurred:", error.message);
showServerErrorMessage();
} else if (error instanceof errors.NotImplemented) {
console.log("Feature not implemented");
showNotImplementedMessage();
} else if (error instanceof errors.BadGateway) {
console.log("Gateway error, please try again");
retryAfterDelay();
} else if (error instanceof errors.Unavailable) {
console.log("Service temporarily unavailable");
showMaintenanceMessage();
}
}Convert any error to a FeathersJS error type for consistent error handling.
/**
* Convert any error to a FeathersJS error
* @param error - Error to convert (Error, object, string, etc.)
* @returns FeathersJS error instance
*/
function convert(error: any): FeathersError;Usage Examples:
import { errors } from "@feathersjs/client";
// Convert various error types
try {
throw new Error("Something went wrong");
} catch (error) {
const feathersError = errors.convert(error);
console.log("Converted error:", feathersError);
}
// Convert HTTP response errors
fetch("/api/users")
.catch(error => {
const feathersError = errors.convert(error);
handleFeathersError(feathersError);
});
// Convert unknown errors
function handleUnknownError(error: unknown) {
const feathersError = errors.convert(error);
logError(feathersError);
}FeathersJS errors can contain additional data and validation information.
Usage Examples:
// Validation errors with detailed field information
try {
await userService.create({
email: "invalid-email",
age: -5
});
} catch (error) {
if (error instanceof errors.Unprocessable) {
console.log("Validation errors:", error.errors);
// error.errors might contain:
// {
// email: "Must be a valid email address",
// age: "Must be a positive number"
// }
// Additional error data
console.log("Error data:", error.data);
}
}
// Conflict errors with resource information
try {
await userService.create({
username: "existing-user"
});
} catch (error) {
if (error instanceof errors.Conflict) {
console.log("Conflict data:", error.data);
// error.data might contain information about the existing resource
}
}Common patterns for handling FeathersJS errors in applications.
Usage Examples:
// Generic error handler
function handleServiceError(error: any) {
if (!(error instanceof errors.FeathersError)) {
error = errors.convert(error);
}
switch (error.code) {
case 400:
showValidationErrors(error.errors || error.message);
break;
case 401:
redirectToLogin();
break;
case 403:
showAccessDeniedPage();
break;
case 404:
show404Page();
break;
case 409:
showConflictMessage(error.data);
break;
case 422:
showValidationErrors(error.errors);
break;
case 429:
showRateLimitMessage();
break;
case 500:
default:
showGenericErrorMessage();
logError(error);
break;
}
}
// Service wrapper with error handling
async function safeServiceCall<T>(
serviceCall: () => Promise<T>,
fallback?: T
): Promise<T | undefined> {
try {
return await serviceCall();
} catch (error) {
handleServiceError(error);
return fallback;
}
}
// Usage
const users = await safeServiceCall(
() => userService.find(),
[] // fallback to empty array
);Handle errors in real-time Socket.IO connections.
Usage Examples:
// Service-level error events
const userService = app.service("users");
userService.on("error", (error) => {
console.error("Real-time service error:", error);
if (error instanceof errors.NotAuthenticated) {
// Handle authentication errors in real-time
app.logout().then(() => {
window.location.href = "/login";
});
}
});
// Connection-level error handling
app.io.on("error", (error) => {
console.error("Socket connection error:", error);
showConnectionErrorMessage();
});
app.io.on("connect_error", (error) => {
console.error("Failed to connect:", error);
showConnectionFailedMessage();
});interface FeathersErrorJSON {
name: string;
message: string;
code: number;
className: string;
data?: any;
errors?: any;
}
type ErrorMessage = string | Error | FeathersErrorJSON;