Alibaba Cloud SDK:Java SDK FAQ

• Java 1.8 ou superior instalado.

• Sua rede consegue alcançar os endpoints da API do Alibaba Cloud.

• Problemas na passagem de parâmetros AK.

• unable to get credentials from any of the providers in the chain: ...

• code 403, You are not authorized to do this operation. Action: xxxx

• Erro ao importar dependências Maven: Could not find artifact com.aliyun:XX:XX

• java: Error: release version X not supported.

• java: Compilation failed: internal java compiler error.

• Code 400: A parameter is required for this action.

• java.lang.NoSuchMethodError, java.lang.NoSuchFieldError

• "TeaUnretryableException: timeout", "java.net.SocketTimeoutException: connect timed out", "java.net.SocketTimeoutException: Read timed out", "SDK.ServerUnreachable", "Connection aborted" ou "RemoteDisconnected".

• Your request is denied as lack of SSL protection. RequestId.

• code: 404, Specified API is not found. Please check your URL and method.

• Unexpected response code for CONNECT: 400.

Can not set java.lang.String field com.aliyun.imm20200930.models.GenerateWebofficeTokenShrinkRequest.userShrink to java.util.

• Falha ao baixar dependências automaticamente com Maven no IDEA.

• Como evitar mensagens WARNING causadas por reflection.

• Specified signature does not match our calculation.

• SDK.EndpointResolvingError: "No such region 'cn-XX'. Please check your region ID".

• [Failed to instantiate [com.aliyuncs.IAcsClient]: Factory method 'iAcsClient' threw exception with message: org/apache/http/conn/ssl/DefaultHostnameVerifier.](#9a870e8cf23tc)

• Erro ao chamar uma OpenAPI: code: 401, You have not activated the XXX service, ou mensagem semelhante.

• Failed to get RAM session credentials from ECS metadata service. HttpCode=XX

• There is a risk of leakage of this AccessKey

• Request was denied due to API flow control

• Specified access key denied due to access policy

• com.aliyuncs.exceptions.ClientException: SDK.InvalidRegionId: Can not find endpoint to access

Problemas na passagem de parâmetros AK.

Se sua mensagem de erro contiver um dos itens abaixo, o AccessKey não está configurado corretamente:

• SDK V2.0: Cannot invoke "com.aliyun.credentials.Client.getCredential()" because "this._credential" is null.

• SDK V1.0: ErrCode: MissingAccessKeyId. ErrMsg: AccessKeyId is mandatory for this action.

Solução:

1. Verifique se ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET estão definidos:

   Linux/macOS

   echo $ALIBABA_CLOUD_ACCESS_KEY_ID
   echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

   Windows

   echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
   echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

   Se os valores retornados estiverem corretos, a configuração foi bem-sucedida. Caso contrário, reconfigure-os conforme descrito em Configurar variáveis de ambiente em sistemas Linux, macOS e Windows.

2. Revise seu código em busca de erros relacionados ao AK.

   Exemplo incorreto comum:

   Config config = new Config()
            .setAccessKeyId(System.getenv("yourAccessKeyID"))   
            .setAccessKeySecret(System.getenv("yourSecret")); 

   Exemplo correto:

   Config config = new Config()
           .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
           .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

   Nota

   System.getenv() recupera o AccessKey ID e o Secret das variáveis de ambiente.

   Importante

   Não codifique seu AccessKey diretamente no código de produção. Essa prática representa um risco de segurança.

unable to get credentials from any of the providers in the chain : ...

Causa: Seu projeto usa o provedor de credenciais padrão (conforme mostrado abaixo), mas nenhum dos tipos de credencial suportados está configurado.

com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
        .setCredential(credential);

Solução:

• Para usar um AccessKey diretamente:

  com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
          // This example shows how to get the AccessKey ID from an environment variable.
          .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
          // This example shows how to get the AccessKey secret from an environment variable.
          .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

  Para outros tipos de credencial, consulte Gerenciar credenciais de acesso.

• Para continuar usando a credencial padrão, configure qualquer um dos tipos de credencial suportados pela cadeia de provedores de credenciais padrão.

code 403, You are not authorized to do this operation. Action: xxxx.

O usuário RAM, a função ou o grupo de usuários que chama a API não possui a permissão necessária. O campo Action:XXXX na mensagem de erro indica a operação de API negada. Por exemplo, Action:dysms:SendSms significa que a conta não tem permissão para chamar a API SendSms do Short Message Service.

Solução:

1. Entre em contato com um administrador para criar uma política de permissões personalizada com base no documento a seguir: Criar uma política de permissões personalizada.

   Nota

   Esta política permite apenas chamadas SendSms para o Short Message Service (dysms). Substitua a Action pelo serviço e pela API indicados na sua mensagem de erro.

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "dysms:SendSms",
         "Resource": "*"
       }
     ]
   }

2. Conceda permissões à conta RAM:

   • Gerenciar permissões de usuário RAM.

   • Gerenciar permissões de função RAM.

   • Conceder permissões a um grupo de usuários RAM.

Erro ao importar dependências Maven: Could not find artifact com.aliyun:XX:XX

Descrição:

O Maven não encontra a dependência especificada.

Solução:

Configure o repositório central do Maven no seu projeto usando um dos métodos a seguir:

• Adicione o seguinte conteúdo ao arquivo pom.xml:

  <repositories>
      <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
      </repository>
      <repository>
          <id>nexus-noke</id>
          <url>http://nexus.noke.com/nexus/content/groups/public/</url>
      </repository>
  </repositories>

• Adicione o seguinte conteúdo ao arquivo settings.xml:

  <settings>
      <!-- Existing settings -->
      
      <mirrors>
          <mirror>
              <!-- This id can be any unique identifier -->
              <id>central</id>
              <mirrorOf>central</mirrorOf>
              <name>Maven Central Mirror</name>
              <url>https://repo1.maven.org/maven2</url>
          </mirror>
      </mirrors>
  </settings>

java: Error: release version X not supported.

No IntelliJ IDEA, pressione Ctrl+Alt+Shift+S para abrir Project Structure. Selecione Modules e defina Language Level para corresponder à versão do seu JDK (por exemplo, "8 - Lambdas, type annotations etc." para JDK 8). Clique em Apply e depois em OK.

java: Compilation failed: internal java compiler error.

No IntelliJ IDEA, acesse File > Settings > Build, Execution, Deployment > Compiler > Java Compiler. Defina Project bytecode version e Target bytecode version para corresponder à versão do seu JDK (por exemplo, 8 para JDK 8). Clique em Apply e depois em OK.

code: 400, <CERTAIN_FIELD > is mandatory for this action.

Falta um parâmetro obrigatório na chamada da API. Solução:

Exemplo usando a API SendSms do Short Message Service:

• Acesse a página de Depuração de API no OpenAPI Portal e selecione o produto de nuvem e a API.

• Compare cuidadosamente o objeto de requisição construído, como SendSmsRequest, para garantir que todos os campos obrigatórios, como número de telefone e assinatura, estejam preenchidos.

• Consulte a documentação da API para confirmar os parâmetros obrigatórios.

• Garanta que os valores dos parâmetros obrigatórios sejam válidos (por exemplo, verifique se o formato do número de telefone está correto).

• O SDK valida os parâmetros antes de chamar a API. Se um parâmetro obrigatório estiver ausente, você receberá um erro MissingRequiredParameter. Por exemplo, a falta do número de telefone retorna "MissingPhoneNumbers: code: 400".

SendSmsRequest sendSmsRequest = new SendSmsRequest()
        // Replace with the phone number that will receive the text message.
        .setPhoneNumbers("<YOUR_VALUE>")
        // Replace with your SMS signature.
        .setSignName("<YOUR_VALUE>")
        // Replace with your SMS template code.
        .setTemplateCode("<YOUR_VALUE>");

java.lang.NoSuchMethodError, java.lang.NoSuchFieldError

Causa:

Essa exceção ocorre quando o runtime Java chama um método ou acessa um campo inexistente. Causas comuns:

• Versão de dependência desatualizada no pom.xml do Maven ou build.gradle do Gradle.

• Conflito de dependências: existem múltiplas versões da mesma dependência, fazendo com que uma versão inferior seja carregada em tempo de execução.

• Cache obsoleto: após atualizar uma dependência, o projeto não foi recompilado ou o cache não foi limpo.

• As versões de dependência em tempo de compilação e em tempo de execução diferem.

• Conflito de classpath: o classpath errado foi selecionado durante a importação.

Solução:

1. Verifique o exemplo fornecido no Alibaba Cloud OpenAPI Portal para identificar possíveis erros no classpath.

2. Se o classpath estiver correto, obtenha a classe específica que causou o erro nas informações da pilha de exceções e localize a dependência e a versão correspondentes.

3. Execute o comando a seguir para visualizar as dependências diretas e transitivas do projeto, além de conflitos e duplicatas específicos.

   • Maven: O Maven usa "menor caminho primeiro" e "ordem de declaração primeiro" para resolver versões de dependências. Resolva conflitos ajustando a ordem das dependências.

     mvn dependency:tree -Dverbose

   • Gradle: O Gradle usa "versão mais alta primeiro" por padrão; portanto, apenas versões desatualizadas causam problemas. Pule para a etapa 4 para obter a versão mais recente.

4. Na saída da árvore de dependências, verifique se há conflitos. Se encontrados, mova a versão mais alta da dependência conflitante para o topo da seção <dependencies></dependencies> no pom.xml. Execute mvn clean install -U para recompilar. Se o erro persistir, continue abaixo.

5. Encontre a versão mais recente da dependência em Pacotes de dependências comuns do Java SDK V2.0. Atualize a versão no seu pom.xml ou build.gradle.

6. Limpe e recompile o projeto:

   • Maven

     mvn clean install -U

   • Gradle:

     gradle clean build --refresh-dependencies

7. Verifique se o problema foi resolvido.

Exemplo:

A mensagem de exceção é java.lang.NoSuchMethodError: com.aliyun.credentials.Client.getCredential().

1. Após verificação, o classpath está correto.

2. De acordo com a mensagem de exceção, o erro ocorreu na classe com.aliyun.credentials.Client, que pertence à dependência credentials-java. A versão referenciada atualmente é 0.2.4.

3. Após executar mvn dependency:tree -Dverbose, constatou-se que a dependência pai credentials-java, tea-openapi, apresenta um conflito de versão. A versão referenciada atualmente é 0.3.2, e a versão conflitante é 0.3.8. Recomendamos mover a dependência pai correspondente à versão tea-openapi 0.3.8 para o topo da seção <dependencies></dependencies>.

4. Execute o comando mvn clean install -U para limpar e recompilar o projeto e verifique se o problema foi resolvido.

5. Se o problema persistir, obtenha a versão mais recente de credentials-java no Maven Central: com.aliyun:credentials-java e adicione manualmente a dependência ao arquivo pom.xml.

"TeaUnretryableException: timeout", "java.net.SocketTimeoutException: connect timed out", "java.net.SocketTimeoutException: Read timed out", "SDK.ServerUnreachable", "Connection aborted" ou "RemoteDisconnected".

Problemas de timeout têm várias causas comuns:

// Runtime parameter timeout setting. This is effective only for requests that use this runtime parameter instance.
RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.connectTimeout = 5000;

// Runtime parameter timeout setting. This is effective only for requests that use this runtime parameter instance.
RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.readTimeout = 10000;

Your request is denied as lack of ssl protect.RequestId .

A API exige HTTPS, mas sua requisição usou HTTP.

Solução:

• Para o SDK V1.0, defina o protocolo HTTPS no objeto Request:

  request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS);

• Use o SDK V2.0, que utiliza HTTPS por padrão.

code: 404, Specified api is not found, please check your url and method.

Você inseriu um Endpoint ou RegionId incorreto. Solução:

Verifique se sua região suporta o serviço desejado. Encontre o Endpoint do produto na página inicial dele no OpenAPI Developer Portal. Exemplo com Short Message Service:

Unexpected response code for CONNECT: 400.

Um nó intermediário interceptou a requisição e ela não chegou ao gateway do Alibaba Cloud.

Solução:

• A configuração de proxy pode estar incorreta. Teste com: curl https://<nome de domínio do serviço Alibaba Cloud>/ -v -x <IP do proxy>:<porta do proxy> (por exemplo, curl https://ecs-cn-hangzhou.aliyuncs.com/ -v -x 127.0.0.1:3128).

• Um firewall interno pode estar bloqueando a requisição. Tente trocar de rede (por exemplo, conecte-se a um hotspot móvel).

Can not set java.lang.String field com.aliyun.imm20200930.models.GenerateWebofficeTokenShrinkRequest.userShrink to java.util .

Uma versão antiga do pacote Tea não consegue converter uma estrutura complexa em String, causando este erro.

Solução:

Atualize o pacote Tea para a versão 1.2.7 ou superior:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>tea</artifactId>
  <version>1.2.7</version>
</dependency>

Falha ao baixar dependências automaticamente com Maven no IDEA.

• Atualize o repositório Maven

  Abra o menu "File" e selecione "Settings" (ou "Preferences"). No painel de navegação à esquerda, expanda "Build, Execution, Deployment" e selecione "Build Tools" > "Maven". Localize a aba "Repositories", selecione o repositório local, clique no botão "Update" e aguarde a conclusão da atualização.

• Verifique o cache do IDEA

  Abra o menu "File" e selecione "Invalidate Caches...". Na caixa de diálogo exibida, selecione "Invalidate and Restart" e aguarde o IDEA limpar o cache e reiniciar.

  

• Verifique a conexão de rede

  Se o Maven não conseguir se conectar ao repositório central ou a outros repositórios remotos, talvez não consiga baixar as dependências. Garanta que sua conexão de rede esteja normal e que nenhum firewall ou servidor proxy esteja bloqueando o acesso do Maven.

• Verifique a configuração do Maven

  Confira se o arquivo de configuração do Maven (geralmente settings.xml) está configurado corretamente. Garanta que "localRepository" aponte para o caminho correto do repositório local e que "mirrors", "proxies" e "profiles" estejam configurados adequadamente.

Como evitar mensagens WARNING causadas por reflection.

Ao usar o Alibaba Cloud SDK com uma versão mais recente do JDK, avisos relacionados a reflection podem aparecer na saída.

Solução:

Defina a variável de ambiente ALIBABA_CLOUD_SDK_LOG_LEVEL como ERROR para suprimir os avisos:

1. Defina a variável de ambiente:

   Windows

   set ALIBABA_CLOUD_SDK_LOG_LEVEL=ERROR

   Linux/macOS

   export ALIBABA_CLOUD_SDK_LOG_LEVEL=ERROR

2. Confirme a definição da variável de ambiente:

   Windows

   echo %ALIBABA_CLOUD_SDK_LOG_LEVEL%

   Linux/macOS

   echo $ALIBABA_CLOUD_SDK_LOG_LEVEL

3. Inicie sua aplicação. As mensagens de aviso do Alibaba Cloud SDK não serão mais exibidas; apenas mensagens de nível ERROR ou superior aparecerão.

Specified signature does not match our calculation.

A assinatura da requisição não corresponde ao cálculo do lado do servidor. Possíveis causas:

• AccessKey (AK) copiado incorretamente

• Algoritmo de assinatura incorreto

• Os parâmetros da requisição ou sua ordem não atendem aos requisitos da API.

Solução:

1. Verifique se o AccessKey ID e o Secret no seu código correspondem exatamente aos do console (sem espaços extras ou caracteres especiais). Use um AccessKey existente ou crie um novo em Criar um par de AccessKey. Nota: O AccessKey Secret é exibido apenas uma vez no momento da criação.

2. Atualize o commons-codec para evitar erros de cálculo de assinatura:

   Atualize a dependência:

   Maven

   Modifique o arquivo pom.xml.

   <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
      <version>1.15</version> <!-- Updated version -->
   </dependency>

   Após atualizar o número da versão, execute o seguinte comando:

   mvn clean install

   Gradle

   No arquivo build.gradle, adicione ou atualize a dependência:

   dependencies {
        implementation 'commons-codec:commons-codec:1.15' // Updated version
   }

   Execute o seguinte comando para compilar o projeto:

   gradle build

3. Se estiver usando assinatura própria, verifique se a lógica do seu código corresponde ao Mecanismo de corpo de requisição e assinatura V3.

SDK.EndpointResolvingError: "No such region 'cn-XX'. Please check your region ID".

A versão do SDK é muito antiga e não suporta a região ou API desejada. Solução:

Atualize a dependência principal do SDK:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>aliyun-java-sdk-core</artifactId>
  <version>4.7.2</version>
</dependency>

dependencies {
    implementation 'com.aliyun:aliyun-java-sdk-core:4.7.2'
    implementation 'com.aliyun:aliyun-java-sdk-sts:3.1.2'
}

Failed to instantiate [com.aliyuncs.IAcsClient]: Factory method 'iAcsClient' threw exception with message: org/apache/http/conn/ssl/DefaultHostnameVerifier .

Uma versão incompatível do Apache HttpClient está sendo usada com o Alibaba Cloud SDK. Solução:

• Verifique se nenhuma outra biblioteca introduz uma versão incompatível do HttpClient usando o gerenciamento de dependências da sua ferramenta de build.

• Atualize o Apache HttpClient para a versão 4.5.14 ou superior:

  <dependency>
      <groupId>org.apache.httpcomponents.client</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.14</version> <!-- Please check for the latest version -->
  </dependency>

Erro ao chamar uma OpenAPI: code: 401, You have not activated the XXX service, ou mensagem semelhante.

Sua conta Alibaba Cloud não ativou o serviço correspondente. XXX é o nome do serviço (por exemplo, OCR service). Solução:

1. Faça login no console de gerenciamento do serviço correspondente.

2. Localize e ative o recurso necessário.

3. Aguarde a ativação do serviço e chame a API novamente.

Failed to get RAM session credentials from ECS metadata service. HttpCode=XX

A credencial da função RAM da instância (ecs_ram_role) só pode ser usada em uma instância ECS ou ECI com uma função RAM anexada. Consulte Função RAM da instância ECS e Usar uma função RAM de instância ECI chamando uma API.

• Para verificar se essa credencial funciona, execute o seguinte comando na instância ECS:

  • Instância Linux

    # Get the metadata access credential. You must set an expiration time. The request cannot contain the X-Forwarded-For header. 100.100.100.200 is the IPv4 address of the instance metadata service.
    TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<metadata_credential_expiration_time>"`
    # Access instance metadata
    curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/[role-name]

  • Instância Windows (PowerShell)

    # Get the metadata access credential. You must set an expiration time. The request cannot contain the X-Forwarded-For header. 100.100.100.200 is the IPv4 address of the instance metadata service.
    $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<metadata_credential_expiration_time>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
    # Access instance metadata
    Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/ram/security-credentials/[role-name]

  Se a seguinte resposta for retornada, a credencial da função RAM da instância estará disponível:

  {
    "AccessKeyId" : "AccessKeyIdValue",
    "AccessKeySecret" : "AccessKeySecretValue",
    "Expiration" : "2025-07-10T08:37:58Z",
    "SecurityToken" : "SecurityTokenValue",
    "LastUpdated" : "2025-07-10T02:33:26Z",
    "Code" : "Success"
  }

• Para mudar para um tipo diferente de credencial, consulte Gerenciar credenciais de acesso.

There is a risk of leakage of this AccessKey

Causa: Seu AccessKey pode estar em risco de vazamento. O Alibaba Cloud aplicou restrições de proteção.

Solução: Soluções para vazamento de AccessKey.

Request was denied due to api flow control

Causa: As chamadas de API são muito frequentes, acionando limitação de taxa (por exemplo, "ThrottlingException").

Solução:

• Implemente um mecanismo de nova tentativa e aumente o intervalo entre requisições para reduzir a carga.

• Otimize a lógica do código: use processamento em lote ou chamadas assíncronas para reduzir o volume de requisições.

Specified access key denied due to access policy

Causa: Uma política de restrição de acesso à rede do AccessKey limita quais endereços IP de origem podem usar um AccessKey permanente para requisições de API.

Solução:

• Modifique o intervalo de endereços IP na política de restrição de acesso à rede do AccessKey.

• Não ative a política de restrição de acesso à rede do AccessKey.

Política de restrição de acesso à rede do AccessKey.

com.aliyuncs.exceptions.ClientException: SDK.InvalidRegionId : Can not find endpoint to access

Causa: Parâmetros incorretos (como um regionId inválido) impedem o SDK de encontrar o endpoint do serviço.

Solução:

• Verifique se todos os parâmetros de configuração (Endpoint, RegionId, etc.) estão corretos com base na documentação do Alibaba Cloud e nos exemplos de código.

• Depure a API no OpenAPI Developer Portal. Após a depuração bem-sucedida, baixe o projeto de exemplo completo para uso local.

Se você encontrar outros problemas, entre em contato conosco:

• Envie um ticket: Página de envio de tickets do Alibaba Cloud.

• Se tiver necessidades relacionadas ou feedback, adicione o grupo DingTalk para entrar em contato com o suporte técnico do Alibaba Cloud. O número do grupo é 60965016010.