Dev/errors

src/main/java/com/alibaba/dashscope/agentstudio/resource/AgentStudioEventStream.java

@@ -95,12 +95,23 @@ private static ApiException wrapFailure(Throwable t, Response response) {
     } catch (IOException e) {
       log.debug("Failed to read SSE failure response body", e);
     }
-    Status status =
-        Status.builder()
-            .statusCode(code)
-            .code(code >= 500 ? "server_error" : code == 401 ? "auth_error" : "http_error")
-            .message(body.isEmpty() ? "HTTP " + code : body)
-            .build();
+
+    // Try to extract original error code and message from response body
+    String apiCode = "";
+    String apiMessage = body;
+    try {
+      com.google.gson.JsonObject json = com.alibaba.dashscope.utils.JsonUtils.parse(body);
+      if (json.has("code")) {
+        apiCode = json.get("code").getAsString();
+      }
+      if (json.has("message")) {
+        apiMessage = json.get("message").getAsString();
+      }
+    } catch (Exception e) {
+      log.debug("Failed to parse error response body as JSON", e);
+    }
+
+    Status status = Status.builder().statusCode(code).code(apiCode).message(apiMessage).build();
     return new ApiException(status, t);
   }
 

src/main/java/com/alibaba/dashscope/api/AsynchronousApi.java

@@ -6,6 +6,7 @@
 
 import com.alibaba.dashscope.base.HalfDuplexParamBase;
 import com.alibaba.dashscope.common.DashScopeResult;
+import com.alibaba.dashscope.common.ErrorType;
 import com.alibaba.dashscope.common.Status;
 import com.alibaba.dashscope.common.TaskStatus;
 import com.alibaba.dashscope.exception.ApiException;
@@ -18,8 +19,10 @@
 import java.net.HttpURLConnection;
 import java.util.HashMap;
 import java.util.Map;
+import lombok.extern.slf4j.Slf4j;
 
 /** Support DashScope async task CRUD. */
+@Slf4j
 public final class AsynchronousApi<ParamT extends HalfDuplexParamBase> {
   final HalfDuplexClient client;
   ConnectionOptions connectionOptions;
@@ -104,6 +107,10 @@ public DashScopeResult wait(
     int maxWaitMilliseconds = 5 * 1000;
     int incrementSteps = 3;
     int step = 0;
+    int transientErrorCount = 0;
+    final int MAX_TRANSIENT_ERRORS = 20;
+    int transientBackoffMs = 1000;
+    final int MAX_TRANSIENT_BACKOFF_MS = 10000;
     long startTime = System.currentTimeMillis();
     long timeoutMillis = timeoutSeconds > 0 ? timeoutSeconds * 1000L : -1L;
     while (true) {
@@ -113,11 +120,11 @@ public DashScopeResult wait(
           throw new ApiException(
               Status.builder()
                   .statusCode(HttpURLConnection.HTTP_CLIENT_TIMEOUT)
-                  .code("TaskWaitTimeout")
+                  .code(ErrorType.TASK_WAIT_TIMEOUT.getValue())
                   .message(
                       StringUtils.format(
-                          "Waiting for task [%s] timed out after %d ms (timeoutSeconds=%d).",
-                          taskId, elapsed, timeoutSeconds))
+                          "Waiting for task [%s] timed out after %d ms (timeoutSeconds=%d). Encountered %d transient errors (503/504) during polling.",
+                          taskId, elapsed, timeoutSeconds, transientErrorCount))
                   .build());
         }
       }
@@ -163,6 +170,38 @@ public DashScopeResult wait(
             && e.getStatus().getStatusCode() != HttpURLConnection.HTTP_GATEWAY_TIMEOUT) {
           throw e;
         }
+        transientErrorCount++;
+        log.warn(
+            "Transient error during async task polling [taskId={}]: status={}, message={}, retry_count={}, backoff_ms={}",
+            taskId,
+            e.getStatus().getStatusCode(),
+            e.getMessage(),
+            transientErrorCount,
+            transientBackoffMs);
+        if (transientErrorCount >= MAX_TRANSIENT_ERRORS) {
+          throw new ApiException(
+              Status.builder()
+                  .statusCode(e.getStatus().getStatusCode())
+                  .code("TooManyTransientErrors")
+                  .message(
+                      StringUtils.format(
+                          "Encountered %d transient errors (503/504) while waiting for task [%s]. The service may be experiencing issues. Last error: %s",
+                          transientErrorCount, taskId, e.getMessage()))
+                  .build());
+        }
+        long sleepMs = transientBackoffMs;
+        if (timeoutMillis > 0) {
+          long remaining = timeoutMillis - (System.currentTimeMillis() - startTime);
+          if (remaining <= 0) {
+            continue;
+          }
+          sleepMs = Math.min(sleepMs, remaining);
+        }
+        try {
+          Thread.sleep(sleepMs);
+        } catch (InterruptedException ignored) {
+        }
+        transientBackoffMs = Math.min(transientBackoffMs * 2, MAX_TRANSIENT_BACKOFF_MS);
       }
     }
   }

src/main/java/com/alibaba/dashscope/audio/http_tts/HttpSpeechSynthesizer.java

@@ -201,7 +201,7 @@ public void onError(Exception e) {
         Status timeoutStatus =
             Status.builder()
                 .statusCode(408)
-                .code("RequestTimeOut")
+                .code(ErrorType.REQUEST_TIMEOUT.getValue())
                 .message("Timeout waiting for audio data from server.")
                 .build();
         throw new ApiException(timeoutStatus);

src/main/java/com/alibaba/dashscope/audio/ttsv2/SpeechSynthesizerV2.java

@@ -352,16 +352,22 @@ private void handleTaskFinished(JsonObject message) {
   private void handleTaskFailed(JsonObject message) {
     log.error("Task failed: " + message.toString());
     if (callback != null) {
-      String errorMessage = "Unknown error";
-      if (message.has("header") && message.getAsJsonObject("header").has("error_message")) {
-        errorMessage = message.getAsJsonObject("header").get("error_message").getAsString();
+      String errorCode = "";
+      String errorMessage = "";
+      if (message.has("header")) {
+        JsonObject header = message.getAsJsonObject("header");
+        if (header.has("error_code")) {
+          errorCode = header.get("error_code").getAsString();
+        }
+        if (header.has("error_message")) {
+          errorMessage = header.get("error_message").getAsString();
+        }
       }
 
-      // Create a Status object for the ApiException
       com.alibaba.dashscope.common.Status status =
           com.alibaba.dashscope.common.Status.builder()
               .statusCode(-1)
-              .code("TASK_FAILED")
+              .code(errorCode)
               .message(errorMessage)
               .build();
       callback.onError(new ApiException(status));

src/main/java/com/alibaba/dashscope/common/DashScopeResult.java

@@ -68,6 +68,15 @@ protected <T extends Result> T fromResponse(Protocol protocol, NetworkResponse r
             // Set default empty string for successful responses
             this.setMessage("");
           }
+          if (this.getCode() != null && !this.getCode().isEmpty()) {
+            throw new ApiException(
+                Status.builder()
+                    .statusCode(this.getStatusCode())
+                    .code(this.getCode())
+                    .message(this.getMessage())
+                    .requestId(this.getRequestId())
+                    .build());
+          }
         }
         if (jsonObject.has(ApiKeywords.PAYLOAD)) {
           JsonObject payload = jsonObject.getAsJsonObject(ApiKeywords.PAYLOAD);
@@ -132,6 +141,15 @@ protected <T extends Result> T fromResponse(Protocol protocol, NetworkResponse r
         // Set default empty string for successful responses
         this.setMessage("");
       }
+      if (this.getCode() != null && !this.getCode().isEmpty()) {
+        throw new ApiException(
+            Status.builder()
+                .statusCode(this.getStatusCode())
+                .code(this.getCode())
+                .message(this.getMessage())
+                .requestId(this.getRequestId())
+                .build());
+      }
       if (jsonObject.has(ApiKeywords.DATA)) {
         if (jsonObject.has(ApiKeywords.REQUEST_ID)) {
           jsonObject.remove(ApiKeywords.REQUEST_ID);
@@ -230,6 +248,15 @@ public <T extends Result> T fromResponse(
         // Set default empty string for successful responses
         this.setMessage("");
       }
+      if (this.getCode() != null && !this.getCode().isEmpty()) {
+        throw new ApiException(
+            Status.builder()
+                .statusCode(this.getStatusCode())
+                .code(this.getCode())
+                .message(this.getMessage())
+                .requestId(this.getRequestId())
+                .build());
+      }
       if (jsonObject.has(ApiKeywords.DATA)) {
         if (jsonObject.has(ApiKeywords.REQUEST_ID)) {
           jsonObject.remove(ApiKeywords.REQUEST_ID);

src/main/java/com/alibaba/dashscope/common/ErrorType.java

@@ -3,22 +3,26 @@
 
 public enum ErrorType {
 
-  /** The error happens in the response body. */
-  RESPONSE_ERROR("response_error"),
+  /** Network error: DNS failure, connection refused, etc. API did not respond. */
+  NETWORK_ERROR("network error"),
 
-  /** The error happens because the request is canceled. */
-  REQUEST_CANCELLED("request_cancelled"),
+  /** WebSocket connection failed after retries. API returned no content. */
+  CONNECTION_ERROR("ConnectionError"),
 
-  /** The error happens because the network protocol is not supported. */
-  PROTOCOL_UNSUPPORTED("protocol_unsupported"),
+  /** Asynchronous task polling timed out. API is still processing. */
+  TASK_WAIT_TIMEOUT("TaskWaitTimeout"),
 
-  /** The api key is not correct. */
-  API_KEY_ERROR("api_key_error"),
+  /** HTTP TTS waiting for audio data timed out. API returned no error. */
+  REQUEST_TIMEOUT("RequestTimeOut"),
 
-  /** An unknown error. */
-  UNKNOWN_ERROR("unknown_error"),
+  /** JSON parsing failed. Original body preserved in message field. */
+  JSON_PARSE_ERROR("json_parse_error"),
 
-  NETWORK_ERROR("network error"),
+  /** Failed to read response body due to IOException. HTTP status code preserved. */
+  BODY_READ_ERROR("body_read_error"),
+
+  /** Non-JSON content type received (e.g., HTML error page). Original body in message. */
+  NON_JSON_RESPONSE("non_json_response"),
   ;
 
   private final String value;

src/main/java/com/alibaba/dashscope/protocol/okhttp/OkHttpHttpClient.java

@@ -53,7 +53,7 @@ public final class OkHttpHttpClient implements HalfDuplexClient {
   private static final MediaType MEDIA_TYPE_APPLICATION_JSON =
       MediaType.parse("application/json; charset=utf-8");
 
-  private Status parseStreamEventData(String data) {
+  private Status parseStreamEventData(String data, int httpStatusCode) {
     try {
       JsonObject jsonResponse = JsonUtils.parse(data);
       String code = "";
@@ -69,16 +69,16 @@ private Status parseStreamEventData(String data) {
         message = jsonResponse.get(ApiKeywords.MESSAGE).getAsString();
       }
       return Status.builder()
-          .statusCode(400)
+          .statusCode(httpStatusCode)
           .code(code)
           .message(message)
           .requestId(requestId)
           .isJson(true)
           .build();
     } catch (Throwable e) {
       return Status.builder()
-          .statusCode(400)
-          .code(ErrorType.RESPONSE_ERROR.getValue())
+          .statusCode(httpStatusCode)
+          .code("")
           .message(data)
           .isJson(false)
           .build();
@@ -108,11 +108,26 @@ private Status parseFailedJson(int statusCode, String body) {
           .isJson(true)
           .build();
     } catch (Throwable e) {
+      // Try to extract code/message even if standard parsing failed
+      String extractedCode = "";
+      String extractedMessage = body;
+      try {
+        JsonObject json = JsonUtils.parse(body);
+        if (json.has(ApiKeywords.CODE)) {
+          extractedCode = json.get(ApiKeywords.CODE).getAsString();
+        }
+        if (json.has(ApiKeywords.MESSAGE)) {
+          extractedMessage = json.get(ApiKeywords.MESSAGE).getAsString();
+        }
+      } catch (Exception ex) {
+        // Parsing failed, use defaults
+      }
+
       return Status.builder()
           .statusCode(statusCode)
-          .code(ErrorType.RESPONSE_ERROR.getValue())
-          .message(body)
-          .isJson(true)
+          .code(extractedCode.isEmpty() ? "" : extractedCode)
+          .message(extractedMessage)
+          .isJson(!extractedCode.isEmpty())
           .build();
     }
   }
@@ -137,9 +152,9 @@ private Status parseFailed(Response response, Throwable th) {
       } catch (IOException e) {
         return Status.builder()
             .statusCode(response.code())
-            .code(ErrorType.RESPONSE_ERROR.getValue())
-            .message("Failed read response body: " + e.getMessage())
-            .isJson(true)
+            .code("")
+            .message("[SDK] Failed to read response body: " + e.getMessage())
+            .isJson(false)
             .build();
       }
       return parseFailedJson(response.code(), body);
@@ -155,24 +170,47 @@ private Status parseFailed(Response response, Throwable th) {
         }
         return Status.builder()
             .statusCode(response.code())
-            .code(ErrorType.RESPONSE_ERROR.getValue())
+            .code("")
             .message(body)
             .isJson(false)
             .build();
       } catch (IOException e) {
         return Status.builder()
             .statusCode(response.code())
-            .code(ErrorType.RESPONSE_ERROR.getValue())
-            .message("Failed read response body: " + e.getMessage())
-            .isJson(true)
+            .code("")
+            .message("[SDK] Failed to read SSE response body: " + e.getMessage())
+            .isJson(false)
             .build();
       }
     } else {
+      String body = "";
+      try {
+        body = response.body().string();
+      } catch (IOException e) {
+        log.debug("Failed to read non-JSON response body", e);
+      }
+
+      // Try to extract code/message from body even if Content-Type is not application/json
+      String extractedCode = "";
+      String extractedMessage = body.isEmpty() ? response.message() : body;
+
+      try {
+        JsonObject json = JsonUtils.parse(body);
+        if (json.has(ApiKeywords.CODE)) {
+          extractedCode = json.get(ApiKeywords.CODE).getAsString();
+        }
+        if (json.has(ApiKeywords.MESSAGE)) {
+          extractedMessage = json.get(ApiKeywords.MESSAGE).getAsString();
+        }
+      } catch (Exception ex) {
+        // Parsing failed, use defaults
+      }
+
       return Status.builder()
           .statusCode(response.code())
-          .code(ErrorType.RESPONSE_ERROR.getValue())
-          .message(response.message())
-          .isJson(false)
+          .code(extractedCode.isEmpty() ? "" : extractedCode)
+          .message(extractedMessage)
+          .isJson(!extractedCode.isEmpty())
           .build();
     }
   }
@@ -255,6 +293,10 @@ public DashScopeResult send(HalfDuplexRequest req) throws NoApiKeyException, Api
                   .build(),
               req.getIsFlatten(),
               req);
+    } catch (ApiException e) {
+      throw e;
+    } catch (NoApiKeyException e) {
+      throw e;
     } catch (Throwable e) {
       throw new ApiException(e);
     }
@@ -308,7 +350,7 @@ private void handleSSEEvent(
       HalfDuplexRequest req) {
     log.debug(StringUtils.format("Event: id %s, type: %s, data: %s", id, eventType, data));
     if (SSEEventType.ERROR.equals(eventType)) {
-      Status st = parseStreamEventData(data);
+      Status st = parseStreamEventData(data, response.code());
       emitter.onError(new ApiException(st));
     } else if (SSEEventType.DATA.equals(eventType) || SSEEventType.RESULT.equals(eventType)) {
       emitter.onNext(
@@ -453,7 +495,7 @@ public void onEvent(
                   java.lang.String data) {
                 log.debug(StringUtils.format("Event: id %s, type: %s, data: %s", id, type, data));
                 if (SSEEventType.ERROR.equals(type)) {
-                  Status st = parseStreamEventData(data);
+                  Status st = parseStreamEventData(data, response.code());
                   callback.onError(new ApiException(st));
                 } else if (SSEEventType.DATA.equals(type) || SSEEventType.RESULT.equals(type)) {
                   callback.onEvent(