Tratamento de erros no Elastic Transcoder

Quando você envia solicitações e obtém respostas da API do Elastic Transcoder, podem ocorrer dois tipos de erro de API:

• Erros de cliente: Os erros de cliente são indicados por um código de resposta HTTP 4xx. Os erros de cliente indicam que o Elastic Transcoder encontrou um problema com a solicitação do cliente, como uma falha de autenticação ou ausência dos parâmetros necessários. Corrija primeiro o problema no aplicativo cliente para enviar a solicitação novamente.

• Erros de servidor: Os erros de servidor são exibidos por um código de resposta HTTP 5xx e precisam ser solucionados pela Amazon. Você pode enviar a solicitação novamente até ter êxito.

Para cada erro de API, o Elastic Transcoder retorna os seguintes valores:

• Um código de status, por exemplo, 400

• Um código de erro, por exemplo, ValidationException

• Uma mensagem de erro, por exemplo, Supplied AttributeValue is empty, must contain exactly one of the supported datatypes

Para obter uma lista de códigos de erro que o Elastic Transcoder retorna para clientes e servidores, consulte Códigos de erro de API (erros de cliente e servidor).

Além disso, você pode encontrar erros enquanto o Elastic Transcoder está processando seu trabalho. Para obter mais informações, consulte Erros durante o processamento do trabalho.

Códigos de erro de API (erros de cliente e servidor)

Os códigos de status HTTP indicam se uma operação foi ou não bem-sucedida.

Um código de resposta de 200 indica que a operação teve êxito. Outros códigos de erro indicam um erro de cliente (4xx) ou um erro de servidor (5xx).

A tabela a seguir relaciona erros retornados pelo Elastic Transcoder. Alguns erros são resolvidos simplesmente tentando enviar novamente a mesma solicitação. A tabela indica quais erros tendem a ser solucionados com novas tentativas sucessivas. Se o valor da coluna Tentar novamente:

• Sim: Envie a mesma solicitação novamente.

• Não: Corrija o problema no cliente primeiro para enviar uma nova solicitação.

Para mais informações sobre enviar novamente uma mesma solicitação, consulte Repetições de erro e recuo exponencial.

Código de status HTTP	Código de erro	Message	Causa	Tentar novamente
400	Conditional Check Failed Exception	The conditional request failed.	Exemplo: O valor esperado não correspondeu com o que foi armazenado no sistema.	Não
400	Incomplete Signature Exception	The request signature does not conform to AWS standards.	A assinatura na solicitação não incluiu todos os componentes necessários. Consulte Conteúdo de cabeçalho HTTP.	Não
403	Missing Authentication Token Exception	The request must contain a valid (registered) AWS Access Key ID.	A solicitação não incluiu o x-amz-security-token necessário. Consulte Faze4r solicitações HTTP para o Elastic Transcoder.	Não
400	Validation Exception	Diversas.	Um ou mais valores em uma solicitação estavam faltando ou eram inválidos; por exemplo, um valor estava vazio ou era superior ao valor válido máximo.	Não
403	AccessDenied Exception	Deleting a system preset is not allowed: account=<accountId>, presetId=<presetId>. General authentication failure. The client did not correctly sign the request. Consulte Solicitações de assinatura.	Você tentou excluir uma predefinição de sistema, a assinatura em uma chamada à API do Elastic Transcoder era inválida ou um usuário não tem autorização para executar a operação.	Não
404	ResourceNot Found Exception	The specified <resource> could not be found: <resourceId>. The specified job was not found: account=<accountId>, jobId=<jobId>. The specified pipeline was not found: account=<accountId>, pipelineId=<pipelineId> The specified preset was not found: account=<accountId>, presetId=<presetId>	Exemplo: o pipeline ao qual você está tentando adicionar um novo trabalho não existe ou ainda está sendo criado.	Não
409	Resource InUse Exception	The <resource> was already in use: accountId=<accountId>, resourceId=<resourceId>. The pipeline contains active jobs: account=<accountId>, pipeline=<pipelineId>.	Exemplo: você tentou excluir um pipeline que está sendo usado no momento.	Não
429	Limit Exceeded Exception	The account already has the maximum number of pipelines allowed: account=<accountId>, maximum number of pipelines=<maximum> The account already has the maximum number of presets allowed: account=<accountId>, maximum number of presets=<maximum> The account already has the maximum number of jobs per pipeline in the backlog: account=<accountId>, maximum number of jobs in backlog for pipeline=<maximum>	A atual conta da AWS atual excedeu limites nos objetos do Elastic Transcoder. Para obter mais informações, consulte Limites de número de pipelines, trabalhos e predefinições do Elastic Transcoder .
429	Provisioned Throughput Exceeded Exception	You exceeded your maximum allowed provisioned throughput.	Exemplo: Sua taxa de solicitação é muito alta. Os SDKs da AWS para o Elastic Transcoder tentam automaticamente novas solicitações para receber essa exceção. Sua solicitação em algum momento terá êxito, a menos que a fila de novas tentativas seja muito grande para concluir. Reduza a frequência de solicitações. Para obter mais informações, consulte Repetições de erro e recuo exponencial. Se você estiver sondando para determinar o status de uma solicitação, considere o uso de notificações para determinar o status. Para obter mais informações, consulte Notificações de status de trabalho.	Sim
429	Throttling Exception	Rate of requests exceeds the allowed throughput.	Você está enviando as solicitações muito rapidamente; por exemplo, solicitações para criar novos trabalhos. Se você estiver sondando para determinar o status de uma solicitação, considere o uso de notificações para determinar o status. Para obter mais informações, consulte Notificações de status de trabalho.	Sim
500	Internal Failure	The server encountered an internal error trying to fulfill the request.	O servidor encontrou um erro ao processar sua solicitação.	Sim
500	Internal Server Error	The server encountered an internal error trying to fulfill the request.	O servidor encontrou um erro ao processar sua solicitação.	Sim
500	Internal Service Exception		The service encountered an unexpected exception while trying to fulfill the request.	Sim
500	Service Unavailable Exception	The service is currently unavailable or busy.	Houve um erro inesperado no servidor ao processar sua solicitação.	Sim

Resposta de erro de exemplo

A seguir é apresentada uma resposta HTTP que indica que o valor para inputBucket era nulo, e nulo não é um valor válido.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: b0e91dc8-3807-11e2-83c6-5912bf8ad066
x-amzn-ErrorType: ValidationException
Content-Type: application/json
Content-Length: 124
Date: Mon, 26 Nov 2012 20:27:25 GMT

{"message":"1 validation error detected: Value null at 'inputBucket' failed to satisfy constraint: Member must not be null"}

Erros durante o processamento do trabalho

Quando o Elastic Transcoder encontra um erro ao processar seu trabalho, ele relata o erro de duas formas:

• Status do trabalho e da saída: o Elastic Transcoder define o objeto Outputs:Status e o objeto Job:Status para a saída com falha como Error. Além disso, o Elastic Transcoder define o objeto JSON Outputs:StatusDetail da saída com falha como um valor que explica a falha.

• Notificação do SNS: se você configurou o pipeline para enviar uma notificação do SNS quando o Elastic Transcoder encontrar um erro durante o processamento, o Elastic Transcoder incluirá um objeto JSON na notificação no seguinte formato:

  {
     "state" : "PROGRESSING|COMPLETED|WARNING|ERROR",
     "errorCode" : "the code of any error that occurred",
     "messageDetails" : "the notification message you created in Amazon SNS",
     "version" : "API version that you used to create the job",
     "jobId" : "value of Job:Id object that Elastic Transcoder 
               returns in the response to a Create Job request",
     "pipelineId" : "value of PipelineId object 
                    in the Create Job request",
     "input" : {
        job Input settings
     },
     "outputKeyPrefix" : "prefix for file names in Amazon S3 bucket",
     "outputs": [
        {
           applicable job Outputs settings,
           "status" : "Progressing|Complete|Warning|Error"
        },
        {...}
     ],
     "playlists": [
        {
           applicable job playlists settings
        }
     ],
     "userMetadata": {
        "metadata key": "metadata value"
     }
  }

Valor de errorCode	Valor de messageDetails	Causa
1000	Erro de validação	Ao processar o trabalho, o Elastic Transcoder determinou que um ou mais valores na solicitação eram inválidos.
1001	Erro de dependência	O Elastic Transcoder não conseguiu gerar a lista de reprodução porque encontrou um erro com uma ou mais dependências de listas de reprodução.
2000	Não é possível assumir a função	O Elastic Transcoder não pode assumir a função do AWS Identity and Access Management especificada no objeto Role no pipeline deste trabalho.
3000	Erro de armazenamento não classificado
3001	A entrada não existe	Não existe nenhum arquivo com o nome especificado no objeto Input:Key deste trabalho. O arquivo deve existir no bucket do Amazon S3 especificado no objeto InputBucket no pipeline deste trabalho.
3002	A saída já existe	Já existe um arquivo com o nome que você especificou no objeto Outputs:Key (ou Output:Key) deste trabalho. O arquivo não pode existir no bucket do Amazon S3 especificado no objeto OutputBucket no pipeline deste trabalho.
3003	Não tem permissão de leitura	A função do IAM especificada no objeto Role no pipeline usado para este trabalho não tem permissão para ler a partir do bucket do Amazon S3 que contém o arquivo que você deseja transcodificar.
3004	Não tem permissão de gravação	A função do IAM especificada no objeto Role no pipeline usado para este trabalho não tem permissão para gravar no bucket do Amazon S3 no qual você deseja salvar arquivos transcodificados ou arquivos de miniaturas.
3005	O bucket não existe	O bucket do S3 especificado não existe: bucket={1}.
3006	Não tem permissão de gravação	O Elastic Transcoder não foi capaz de gravar a key={1} no bucket={2}, pois a chave não está na mesma região que o bucket
4000	Arquivo de entrada inválido	O arquivo que você especificou no objeto Input:Key deste trabalho está em um formato que atualmente não é compatível com o Elastic Transcoder.
4001	Arquivo de entrada inválido	A largura x altura do arquivo que você especificou no objeto Input:Key deste trabalho excede a largura x altura máxima permitida.
4002	Arquivo de entrada inválido	O tamanho do arquivo que você especificou no objeto Input:Key deste trabalho excede o tamanho máximo permitido.
4003	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu interpretar o arquivo que você especificou em um dos objetos Outputs:Watermarks:InputKey deste trabalho.
4004	Arquivo de entrada inválido	A largura x altura de um arquivo que você especificou em um dos objetos Outputs:Watermarks:InputKey deste trabalho excede a largura x altura máxima permitida.
4005	Arquivo de entrada inválido	O tamanho de um arquivo que você especificou para um dos objetos {1} excede o tamanho máximo permitido: bucket={2}, key={3}, size{4}, max size={5}.
4006	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu transcodificar o arquivo de entrada porque o formato não é compatível
4007	Arquivo de entrada não processado	O Elastic Transcoder encontrou um tipo de arquivo que geralmente é compatível, mas não foi capaz de processar o arquivo corretamente. Este erro abriu automaticamente um caso de suporte, e começamos a pesquisar a causa do problema.
4008	Arquivo de entrada inválido	A causa subjacente é uma incompatibilidade entre a predefinição e o arquivo de entrada. Os exemplos incluem: A predefinição inclui as configurações de áudio, mas o arquivo de entrada não possui áudio. A predefinição inclui as configurações de vídeo, mas o arquivo de entrada não possui vídeo.
4009	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu inserir todas as suas artes do álbum no arquivo de saída porque você excedeu o número máximo de fluxos de arte.
4010	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu interpretar o arquivo gráfico que você especificou para AlbumArt:Artwork:InputKey.
4011	Arquivo de entrada inválido	O Elastic Transcoder detectou um fluxo de arte incorporado, mas não conseguiu interpretá-lo.
4012	Arquivo de entrada inválido	A imagem que você especificou para AlbumArt:Artwork excede a largura x altura máxima permitida: 4096 x 3072.
4013	Arquivo de entrada inválido	A largura x altura da arte incorporada excede a largura x altura máxima permitida: 4096 x 3072.
4014	Entrada inválida	O valor que você especificou para a hora de início de um clipe é posterior ao término do arquivo de entrada. O Elastic Transcoder não conseguiu criar um arquivo de saída.
4015	Entrada inválida	O Elastic Transcoder não conseguiu gerar um arquivo manifesto porque os segmentos gerados não eram correspondentes.
4016	Entrada inválida	O Elastic Transcoder não conseguiu descriptografar o arquivo de entrada em {1} usando {2}.
4017	Entrada inválida	A chave AES foi criptografada com uma chave de criptografia de {2} bits. AES suporta apenas chaves de criptografia de 128, 192 e 256 bits. MD5={1}.
4018	Entrada inválida	O Elastic Transcoder não conseguiu descriptografar a chave cifrada com MD5={1}
4019	Entrada inválida	O Elastic Transcoder não conseguiu gerar uma chave de dados usando o ARN da chave do KMS {0}.
4020	Entrada inválida	Sua chave deve ter 128 bits para criptografia AES-128. MD5={1}, {2} bits.
4021	Entrada inválida	Sua chave deve ter 128 bits para PlayReady DRM. MD5={1}, strength={2} bits.
4022	Entrada inválida	O tamanho total dos {1} arquivos de mídia especificados excede o tamanho máximo permitido: bucket={2}, size={3}.
4023	Entrada inválida	Os {1} arquivos de entrada especificados para concatenação não criarão uma saída com uma resolução consistente com a predefinição especificada. Use uma predefinição com diferentes configurações de PaddingPolicy, SizingPolicy, MaxWidth e MaxHeight.
4024	Entrada inválida	Os {1} arquivos de entrada especificados para concatenação não criarão miniaturas com uma resolução consistente com a predefinição especificada. Use uma predefinição com diferentes configurações de miniatura PaddingPolicy, SizingPolicy, MaxWidth e MaxHeight.
4025	Entrada inválida	Pelo menos um arquivo de mídia (entrada #{1}) não corresponde aos outros. Todos os arquivos de mídia devem ter vídeo ou nenhum vídeo.
4026	Entrada inválida	Pelo menos um arquivo de mídia (entrada #{1}) não corresponde aos outros. Todos os arquivos de mídia devem ter áudio ou nenhum áudio.
4100	Arquivo de entrada inválido	O Elastic Transcoder detectou uma trilha de legendas incorporada, mas não conseguiu interpretá-la.
4101	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu interpretar o arquivo de legenda especificado para o bucket do Amazon S3={1}, key={2}.
4102	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu interpretar o arquivo de legenda especificado, pois ele não tinha codificação UTF-8: bucket do Amazon S3={1}, key={2}.
4103	Arquivo de entrada inválido	O Elastic Transcoder não foi capaz de processar todas as trilhas de legenda porque você excedeu {1}, o número máximo de trilhas de legenda.
4104	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu gerar uma lista de reprodução principal porque a saída desejada contém {1} legendas incorporadas, quando o máximo é 4.
4105	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu incorporar as trilhas de legenda porque a taxa de quadros {1} não é compatível com a CEA-708. Apenas taxas de quadros [29,97, 30] são compatíveis.
4106	Arquivo de entrada inválido	O Elastic Transcoder não conseguiu incorporar as trilhas de legenda porque o formato {1} oferece suporte apenas a trilhas de legenda {2}.
9000	Erro de serviço interno
9001	Erro de serviço interno
9999	Erro de serviço interno

Identificação de erros

Para que seu aplicativo seja executado consistentemente, você precisa criar uma lógica para identificar erros e responder. Uma postura comum é implementar sua solicitação em um bloco try ou em uma declaração if-then.

Os SDKs da AWS realizam por conta própria novas tentativas e verificação de erros. Se você encontrar um erro ao usar um dos SDKs da AWS, provavelmente verá o código de erro e a descrição. Provavelmente você verá também o valor Request ID. O valor Request ID pode ajudar a resolver problemas junto ao suporte do Elastic Transcoder.

O exemplo a seguir usa o AWS SDK para Java para excluir um item em um bloco try e usa um bloco catch para responder ao erro. Nesse caso, ele informa que a solicitação falhou. O exemplo usa a classe AmazonServiceException para recuperar informações sobre quaisquer erros de operação, incluindo o Request ID. O exemplo também usa a classe AmazonClientException caso a solicitação não seja bem-sucedida por outros motivos.

try {
   DeleteJobRequest request = new DeleteJobRequest(jobId);
   DeleteJobResult result = ET.deleteJob(request);
   System.out.println("Result: " + result);
   // Get error information from the service while trying to run the operation	
   }  catch (AmazonServiceException ase) {
      System.err.println("Failed to delete job " + jobId);
      // Get specific error information
      System.out.println("Error Message:    " + ase.getMessage());
      System.out.println("HTTP Status Code: " + ase.getStatusCode());
      System.out.println("AWS Error Code:   " + ase.getErrorCode());
      System.out.println("Error Type:       " + ase.getErrorType());
      System.out.println("Request ID:       " + ase.getRequestId());
   // Get information in case the operation is not successful for other reasons	
   }  catch (AmazonClientException ace) {
      System.out.println("Caught an AmazonClientException, which means"+
      " the client encountered " +
      "an internal error while trying to " +
      "communicate with Elastic Transcoder, " +
      "such as not being able to access the network.");
      System.out.println("Error Message: " + ace.getMessage());
   }

Repetições de erro e recuo exponencial

Vários componentes em uma rede, como servidores DNS, switches, balanceadores de carga e outros, podem gerar erros em qualquer lugar do ciclo de vida de determinada solicitação.

A técnica usual para lidar com essas respostas de erro em um ambiente de rede é implementar novas tentativas no aplicativo cliente. Essa técnica aumenta a confiabilidade do aplicativo e reduz os custos operacionais para o desenvolvedor.

Todo AWS SDK compatível com o Elastic Transcoder implementa a lógica de novas tentativas automáticas. O AWS SDK para Java tentará realizar novas tentativas de solicitação automaticamente. Você pode definir as configurações de novas tentativas usando a classe ClientConfiguration. Por exemplo, em alguns casos, como uma página web que faz uma solicitação com latência mínima sem novas tentativas, você pode querer desativar a lógica de novas tentativas. Use a classe ClientConfiguration e forneça um valor maxErrorRetry de 0 para desativar as novas tentativas.

Se não estiver usando um SDK da AWS;, você deve tentar novamente as solicitações originais que recebem erros do servidor (5xx). No entanto, erros de cliente (4xx, diferente de ThrottlingException ou ProvisionedThroughputExceededException) indicam que você precisa revisar a solicitação para corrigir o problema antes de tentar novamente.

nota

Se você estiver fazendo a sondagem para determinar o status de uma solicitação, e se o Elastic Transcoder estiver retornando o código de status HTTP 429 com um código de erro Provisioned Throughput Exceeded Exception ou Throttling Exception, considere o uso de notificações em vez de sondagem para determinar o status. Para obter mais informações, consulte Notificações de status de trabalho.

Além de novas tentativas simples, é recomendável usar um algoritmo de recuo exponencial para um melhor controle de fluxo. A ideia por trás do backoff exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. Por exemplo, você pode permitir um lapso de 1 segundo antes da primeira nova tentativa, 4 segundos antes da segunda nova tentativa, 16 segundos antes da terceira nova tentativa, e assim por diante. Contudo, se a solicitação não tiver êxito após um minuto, o problema talvez seja um limite fixo e não a taxa de solicitação. Por exemplo, você pode ter atingido o número máximo permitido de pipelines. Defina um tempo de interrupção de cerca de um minuto para o número máximo de novas tentativas.

Veja a seguir um fluxo de trabalho mostrando a lógica de novas tentativas. A lógica de fluxo de trabalho primeiro determina se o erro é um erro de servidor (5xx). Em seguida, se o erro for um erro de servidor, o código repetirá a solicitação original.

currentRetry = 0
DO
  set retry to false

  execute Elastic Transcoder request

  IF Exception.errorCode = ProvisionedThroughputExceededException
    set retry to true
  ELSE IF Exception.httpStatusCode = 500
    set retry to true
  ELSE IF Exception.httpStatusCode = 400
    set retry to false 
    fix client error (4xx)

  IF retry = true  
    wait for (2^currentRetry * 50) milliseconds
    currentRetry = currentRetry + 1

WHILE (retry = true AND currentRetry < MaxNumberOfRetries)  // limit retries