Error Handling¶

{
  "error_code": "CAMERA_NOT_FOUND",
  "message": "Camera 'front_door' not found in database",
  "details": {
    "camera_id": "front_door"
  },
  "request_id": "req-123-456"
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Camera 'front_door' does not exist",
  "instance": "/api/cameras/front_door"
}

from fastapi import status
from backend.api.schemas.errors import ErrorCode, raise_http_error

@router.get("/{camera_id}")
async def get_camera(camera_id: str, db: AsyncSession = Depends(get_db)):
    camera = await db.get(Camera, camera_id)
    if not camera:
        raise_http_error(
            status_code=status.HTTP_404_NOT_FOUND,
            error_code=ErrorCode.CAMERA_NOT_FOUND,
            message=f"Camera '{camera_id}' not found in database",
        )
    return camera

raise_http_error(
    status_code=status.HTTP_400_BAD_REQUEST,
    error_code=ErrorCode.INVALID_DATE_RANGE,
    message="Start date must be before end date",
    details={
        "start_date": "2026-01-15",
        "end_date": "2026-01-10"
    },
    request_id="req-123-456",
)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "errors": [
      {
        "field": "body.start_date",
        "message": "start_date must be before end_date",
        "value": "2026-12-01"
      },
      {
        "field": "body.limit",
        "message": "ensure this value is less than or equal to 1000",
        "value": 5000
      }
    ],
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before retrying.",
    "retry_after": 60,
    "limit": 100,
    "window_seconds": 60,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "AI_SERVICE_UNAVAILABLE",
    "message": "Object detection service temporarily unavailable",
    "service": "yolo26",
    "retry_after": 30,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

COMMON_ERROR_RESPONSES = {
    400: {
        "model": ValidationErrorResponse,
        "description": "Validation error - request data is invalid",
    },
    401: {
        "model": ErrorResponse,
        "description": "Authentication required",
    },
    403: {
        "model": ErrorResponse,
        "description": "Access denied",
    },
    404: {
        "model": ErrorResponse,
        "description": "Resource not found",
    },
    409: {
        "model": ErrorResponse,
        "description": "Conflict - resource already exists",
    },
    429: {
        "model": RateLimitErrorResponse,
        "description": "Rate limit exceeded",
    },
    500: {
        "model": ErrorResponse,
        "description": "Internal server error",
    },
    502: {
        "model": ServiceUnavailableResponse,
        "description": "Bad gateway - upstream service error",
    },
    503: {
        "model": ServiceUnavailableResponse,
        "description": "Service unavailable",
    },
}

from backend.api.schemas.problem_details import get_status_phrase

get_status_phrase(404)  # "Not Found"
get_status_phrase(500)  # "Internal Server Error"
get_status_phrase(429)  # "Too Many Requests"
get_status_phrase(999)  # "Unknown Error"

# Good - specific error code
raise_http_error(
    status_code=404,
    error_code=ErrorCode.CAMERA_NOT_FOUND,
    message="Camera not found",
)

# Avoid - generic error code
raise_http_error(
    status_code=404,
    error_code=ErrorCode.RESOURCE_NOT_FOUND,
    message="Camera not found",
)

raise_http_error(
    status_code=400,
    error_code=ErrorCode.INVALID_DATE_RANGE,
    message="Start date must be before end date",
    details={
        "start_date": str(start_date),
        "end_date": str(end_date),
        "suggestion": "Swap the date values"
    },
)

# Good - sanitized
raise_http_error(
    status_code=401,
    error_code=ErrorCode.INVALID_API_KEY,
    message="Invalid API key",
)

# Bad - exposes key
raise_http_error(
    status_code=401,
    error_code=ErrorCode.INVALID_API_KEY,
    message="Invalid API key",
    details={"provided_key": api_key},  # Never do this!
)

import uuid

request_id = str(uuid.uuid4())
raise_http_error(
    status_code=500,
    error_code=ErrorCode.INTERNAL_ERROR,
    message="An unexpected error occurred",
    request_id=request_id,
)
# Log the request_id for debugging
logger.error(f"Internal error for request {request_id}", exc_info=True)