Error Handling

All API endpoints follow a consistent error handling pattern. When an error occurs, the response will include:

Response Structure

{
  "code": "ERROR_CODE",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/resource",
  "description": "Human readable error description"
}

Field	Type	Description
code	string	A unique error code identifying the type of error
timestamp	string	ISO 8601 timestamp when the error occurred
path	string	The API endpoint path where the error occurred
description	string	A human-readable description of the error

Standard HTTP Status Codes

Status Code	Description
400	Bad Request - The request was malformed or contained invalid parameters
401	Unauthorized - Authentication is required or the provided credentials are invalid
403	Forbidden - The authenticated user doesn't have permission to access the requested resource
404	Not Found - The requested resource does not exist
404	Invalid State - Cannot { HTTP method } { resource path }
409	Conflict - The request conflicts with the current state of the server
422	Unprocessable Entity - The request was well-formed but contains semantic errors
429	Too Many Requests - Rate limit has been exceeded
500	Internal Server Error - An unexpected error occurred on the server
502	Bad Gateway - Invalid response from an upstream server

Common Error Codes

Code	Description	HTTP Status
UNKNOWN_ERROR	Internal server error	500
GENERAL_ERROR	A general error occurred	500
UNAUTHORIZED	Authentication failed or token expired	401
BAD_REQUEST	Invalid request parameters	400
NOT_FOUND	Resource not found	404
FORBIDDEN	Insufficient permissions	403
CONFLICT	Resource conflict	409
INVALID_STATE	Resource not found	404
UNPROCESSABLE	Validation failed	422

Example Error Responses

Authentication Error (401 Unauthorized)

{
  "code": "UNAUTHORIZED",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/users",
  "description": "Token invalid or expired"
}

Validation Error (400 Bad Request)

{
  "code": "BAD_REQUEST",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/users",
  "description": "Invalid input parameters"
}

Resource Not Found (404 Not Found)

{
  "code": "NOT_FOUND",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/users/123",
  "description": "User not found"
}

Permission Error (403 Forbidden)

{
  "code": "FORBIDDEN",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/admin/settings",
  "description": "Insufficient permissions to access this resource"
}

Conflict Error (409 Conflict)

{
  "code": "CONFLICT",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/users",
  "description": "User with this email already exists"
}

Resource Not Found (404 Invalid State)

{
  "code": "INVALID_STATE",
  "timestamp": "2025-07-29T10:00:00.000Z",
  "path": "/api/v1/users/550e8400-e29b-41d4-a716-446655440000/activate",
  "description": "Cannot PATCH /api/v1/users/550e8400-e29b-41d4-a716-446655440000/activate"
}