Return 503 (instead of 500) when trying to deploy a target that is no ready (#536)

* Return 503 (instead of 500) when trying to deploy a target that is not ready

* Add declared exceptions to method comments

Author: jmendeza

src/main/api/deployer-api.yaml

@@ -223,6 +223,8 @@ paths:
                     $ref: '#/components/responses/NotFound'
                 '500':
                     $ref: '#/components/responses/InternalServerError'
+                '503':
+                    $ref: '#/components/responses/ServiceUnavailable'
 
     /api/1/target/deploy/{env}/{site_name}:
         post:
@@ -1041,6 +1043,16 @@ components:
                                 type: string
                                 example: Internal Server Error
 
+        ServiceUnavailable:
+            description: Service unavailable
+            content:
+                application/json:
+                    schema:
+                        type: object
+                        properties:
+                            message:
+                                type: string
+                                example: Not available
         Accepted:
             description: Accepted
             content:

src/main/java/org/craftercms/deployer/api/DeploymentService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2007-2022 Crafter Software Corporation. All Rights Reserved.
+ * Copyright (C) 2007-2026 Crafter Software Corporation. All Rights Reserved.
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as published by
@@ -15,11 +15,12 @@
  */
 package org.craftercms.deployer.api;
 
-import java.util.List;
-import java.util.Map;
-
 import org.craftercms.deployer.api.exceptions.DeploymentServiceException;
 import org.craftercms.deployer.api.exceptions.TargetNotFoundException;
+import org.craftercms.deployer.api.exceptions.TargetNotReadyException;
+
+import java.util.List;
+import java.util.Map;
 
 /**
  * Service for doing deployments.
@@ -46,9 +47,11 @@ public interface DeploymentService {
 	 * @param waitTillDone if the method should wait till the deployment is done or return immediately
 	 * @param params       additional parameters that can be used by the deployment processors
 	 * @return the deployment info
+	 * @throws TargetNotFoundException    if the target for the specified env and site name was not found
 	 * @throws DeploymentServiceException if there was an error while executing the deployments
+	 * @throws TargetNotReadyException    if the target is not ready to accept deployments
 	 */
 	Deployment deployTarget(String env, String siteName, boolean waitTillDone,
-				Map<String, Object> params) throws TargetNotFoundException, DeploymentServiceException;
+							Map<String, Object> params) throws TargetNotFoundException, DeploymentServiceException, TargetNotReadyException;
 
 }

src/main/java/org/craftercms/deployer/impl/DeploymentServiceImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2007-2023 Crafter Software Corporation. All Rights Reserved.
+ * Copyright (C) 2007-2026 Crafter Software Corporation. All Rights Reserved.
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as published by
@@ -82,11 +82,11 @@ public List<Deployment> deployAllTargets(boolean waitTillDone,
 
 	@Override
 	public Deployment deployTarget(String env, String siteName, boolean waitTillDone,
-				       Map<String, Object> params) throws TargetNotFoundException,
-		DeploymentServiceException {
+								   Map<String, Object> params) throws TargetNotFoundException,
+			DeploymentServiceException, TargetNotReadyException {
 		try {
 			return targetService.getTarget(env, siteName).deploy(waitTillDone, params);
-		} catch (TargetServiceException | TargetNotReadyException e) {
+		} catch (TargetServiceException e) {
 			throw new DeploymentServiceException(format("Error while deploying target '%s'", TargetImpl.getId(env, siteName)), e);
 		}
 	}

src/main/java/org/craftercms/deployer/impl/rest/ExceptionHandlers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2007-2023 Crafter Software Corporation. All Rights Reserved.
+ * Copyright (C) 2007-2026 Crafter Software Corporation. All Rights Reserved.
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as published by
@@ -23,6 +23,7 @@
 import org.craftercms.core.controller.rest.ValidationFieldError;
 import org.craftercms.deployer.api.exceptions.TargetAlreadyExistsException;
 import org.craftercms.deployer.api.exceptions.TargetNotFoundException;
+import org.craftercms.deployer.api.exceptions.TargetNotReadyException;
 import org.springframework.core.Ordered;
 import org.springframework.core.annotation.Order;
 import org.springframework.http.HttpHeaders;
@@ -96,6 +97,12 @@ public ResponseEntity<Object> handleInvalidManagementTokenException(InvalidManag
 			request);
 	}
 
+	@ExceptionHandler(TargetNotReadyException.class)
+	public ResponseEntity<Object> handleTargetNotReadyException(TargetNotReadyException ex, WebRequest request) {
+		return handleExceptionInternal(ex, ex.getMessage(), new HttpHeaders(), HttpStatus.SERVICE_UNAVAILABLE,
+				request);
+	}
+
 	@Override
 	protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex, HttpHeaders headers,
 								      HttpStatusCode status, WebRequest request) {