web / lib/utils/api-response
lib/utils/api-response
Provides standardized API response utilities for consistent error handling.
This module defines a standard error response format used across all API routes, ensuring consistent error handling and making it easier for clients to parse and handle errors uniformly.
Interfaces
ErrorResponse
Standard error response format for all API routes.
Properties
error
error:
string
Human-readable error message
code?
optionalcode:string
Optional error code for programmatic handling (e.g., “INVALID_BOUNDS”, “UNAUTHORIZED”)
details?
optionaldetails:unknown
Optional additional error context or details
Functions
apiError()
apiError(
message,status,code?,details?):NextResponse<ErrorResponse>
Create a standardized error response.
Parameters
message
string
Human-readable error message
status
number
HTTP status code
code?
string
Optional error code for programmatic handling
details?
unknown
Optional additional error context
Returns
NextResponse<ErrorResponse>
NextResponse with standardized error format
badRequest()
badRequest(
message,code?):NextResponse<ErrorResponse>
Create a 400 Bad Request error response.
Parameters
message
string
Error message describing what was invalid
code?
string
Optional error code
Returns
NextResponse<ErrorResponse>
NextResponse with 400 status
unauthorized()
unauthorized(
message,code?):NextResponse<ErrorResponse>
Create a 401 Unauthorized error response.
Parameters
message
string = "Unauthorized"
Error message describing the authorization failure
code?
string
Optional error code
Returns
NextResponse<ErrorResponse>
NextResponse with 401 status
forbidden()
forbidden(
message,code?):NextResponse<ErrorResponse>
Create a 403 Forbidden error response.
Parameters
message
string = "Forbidden"
Error message describing the authorization failure
code?
string
Optional error code
Returns
NextResponse<ErrorResponse>
NextResponse with 403 status
notFound()
notFound(
message,code?):NextResponse<ErrorResponse>
Create a 404 Not Found error response.
Parameters
message
string = "Resource not found"
Error message describing what was not found
code?
string
Optional error code
Returns
NextResponse<ErrorResponse>
NextResponse with 404 status
methodNotAllowed()
methodNotAllowed(
message,code?):NextResponse<ErrorResponse>
Create a 405 Method Not Allowed error response.
Parameters
message
string
Error message describing allowed methods
code?
string
Optional error code
Returns
NextResponse<ErrorResponse>
NextResponse with 405 status
internalError()
internalError(
message,code?,details?):NextResponse<ErrorResponse>
Create a 500 Internal Server Error response.
Parameters
message
string = "Internal server error"
Error message (should be generic, not expose internal details)
code?
string
Optional error code
details?
unknown
Optional error details (use cautiously, may expose internals)
Returns
NextResponse<ErrorResponse>
NextResponse with 500 status
createErrorHandler()
createErrorHandler(
context,logger): (error) =>NextResponse<ErrorResponse>
Create an error handler function for API routes.
This factory function creates a consistent error handler that logs errors and returns a standardized 500 response. Use this to eliminate duplicate error handling logic across API routes.
Parameters
context
string
Context string describing what action failed (e.g., “fetching map clusters”)
logger
Logger instance with error method
error
(message, meta?) => void
Returns
Error handler function
(
error):NextResponse<ErrorResponse>
Parameters
error
unknown
Returns
NextResponse<ErrorResponse>
Example
const handleError = createErrorHandler("fetching events", logger);
// In catch block:
return handleError(error);