Menu
Amazon Elastic Transcoder
Developer Guide (API Version 2012-09-25)

Handling Errors in Elastic Transcoder

When you send requests to and get responses from the Elastic Transcoder API, you might encounter two types of API errors:

  • Client errors: Client errors are indicated by a 4xx HTTP response code. Client errors indicate that Elastic Transcoder found a problem with the client request, such as an authentication failure or missing required parameters. Fix the issue in the client application before submitting the request again.

  • Server errors: Server errors are indicated by a 5xx HTTP response code, and need to be resolved by Amazon. You can resubmit/retry the request until it succeeds.

For each API error, Elastic Transcoder returns the following values:

  • A status code, for example, 400

  • An error code, for example, ValidationException

  • An error message, for example, Supplied AttributeValue is empty, must contain exactly one of the supported datatypes

For a list of error codes that Elastic Transcoder returns for client and server errors, see API Error Codes (Client and Server Errors).

In addition, you might encounter errors while Elastic Transcoder is processing your job. For more information, see Errors During Job Processing.

API Error Codes (Client and Server Errors)

HTTP status codes indicate whether an operation is successful or not.

A response code of 200 indicates the operation was successful. Other error codes indicate either a client error (4xx) or a server error (5xx).

The following table lists the errors returned by Elastic Transcoder. Some errors are resolved if you simply retry the same request. The table indicates which errors are likely to be resolved with successive retries. If the value of the Retry column is:

  • Yes: Submit the same request again.

  • No: Fix the problem on the client side before submitting a new request.

For more information about retrying requests, see Error Retries and Exponential Backoff.

HTTP Status Code Error code Message Cause Retry
400 Conditional Check Failed Exception The conditional request failed. Example: The expected value did not match what was stored in the system. No
400 Incomplete Signature Exception The request signature does not conform to AWS standards. The signature in the request did not include all of the required components. See HTTP Header Contents. No
403 Missing Authentication Token Exception The request must contain a valid (registered) AWS Access Key ID. The request did not include the required x-amz-security-token. See Making HTTP Requests to Elastic Transcoder. No
400 Validation Exception Various. One or more values in a request were missing or invalid; for example, a value was empty or was greater than the maximum valid value. No
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. See Signing Requests.

You attempted to delete a system preset, the signature in a call to the Elastic Transcoder API was invalid, or an IAM user is not authorized to perform the operation.

No
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>

Example: The pipeline to which you're trying to add a job doesn't exist or is still being created. No
409 Resource InUse Exception
  • The <resource> was already in use: accountId=<accountId>, resourceId=<resourceId>.

  • The pipeline contains active jobs: account=<accountId>, pipeline=<pipelineId>.

Example: You attempted to delete a pipeline that is currently in use. No
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>

The current AWS account has exceeded limits on Elastic Transcoder objects. For more information, see Limits on the Number of Elastic Transcoder Pipelines, Jobs, and Presets.
429 Provisioned Throughput Exceeded Exception You exceeded your maximum allowed provisioned throughput.

Example: Your request rate is too high. The AWS SDKs for Elastic Transcoder automatically retry requests that receive this exception. Your request is eventually successful unless your retry queue is too large to finish. Reduce the frequency of requests. For more information, see Error Retries and Exponential Backoff.

If you're polling to determine the status of a request, consider using notifications to determine status. For more information, see Notifications of Job Status.

Yes
429 Throttling Exception Rate of requests exceeds the allowed throughput.

You are submitting requests too rapidly; for example, requests to create new jobs.

If you're polling to determine the status of a request, consider using notifications to determine status. For more information, see Notifications of Job Status.

Yes
500 Internal Failure The server encountered an internal error trying to fulfill the request. The server encountered an error while processing your request. Yes
500 Internal Server Error The server encountered an internal error trying to fulfill the request. The server encountered an error while processing your request. Yes
500 Internal Service Exception The service encountered an unexpected exception while trying to fulfill the request. Yes
500 Service Unavailable Exception The service is currently unavailable or busy. There was an unexpected error on the server while processing your request. Yes

Sample Error Response

The following is an HTTP response indicating that the value for inputBucket was null, which is not a valid value.

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"}

Errors During Job Processing

When Elastic Transcoder encounters an error while processing your job, it reports the error in two ways:

  • Job Status and Output Status: Elastic Transcoder sets the Job:Status object and the Outputs:Status object for the failed output to Error. In addition, Elastic Transcoder sets the Outputs:StatusDetail JSON object for the failed output to a value that explains the failure.

  • SNS Notification: If you configured the pipeline to send an SNS notification when Elastic Transcoder encounters an error during processing, Elastic Transcoder includes a JSON object in the notification in the following format:

    { "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|Completed|Warning|Error" }, {...} ], "playlists": [ { applicable job playlists settings } ], "userMetadata": { "metadata key": "metadata value" } }
Value of errorCode Value of messageDetails Cause
1000 Validation Error While processing the job, Elastic Transcoder determined that one or more values in the request were invalid.
1001 Dependency Error Elastic Transcoder could not generate the playlist because it encountered an error with one or more of the playlists dependencies.
2000 Cannot Assume Role Elastic Transcoder cannot assume the AWS Identity and Access Management role that is specified in the Role object in the pipeline for this job.
3000 Unclassified Storage Error
3001 Input Does Not Exist No file exists with the name that you specified in the Input:Key object for this job. The file must exist in the Amazon S3 bucket that is specified in the InputBucket object in the pipeline for this job.
3002 Output Already Exists A file already exists with the name that you specified in the Outputs:Key (or Output:Key) object for this job. The file cannot exist in the Amazon S3 bucket that is specified in the OutputBucket object in the pipeline for this job.
3003 Does Not Have Read Permission The IAM role specified in the Role object in the pipeline that you used for this job doesn't have permission to read from the Amazon S3 bucket that contains the file you want to transcode.
3004 Does Not Have Write Permission The IAM role specified in the Role object in the pipeline that you used for this job doesn't have permission to write to the Amazon S3 bucket in which you want to save either transcoded files or thumbnail files.
3005 Bucket Does Not Exist The specified S3 bucket does not exist: bucket={1}.
3006 Does Not Have Write Permission Elastic Transcoder was unable to write the key={1} to bucket={2}, as the key is not in the same region as the bucket
4000 Bad Input File The file that you specified in the Input:Key object for this job is in a format that is currently not supported by Elastic Transcoder.
4001 Bad Input File The width x height of the file that you specified in the Input:Key object for this job exceeds the maximum allowed width x height.
4002 Bad Input File The file size of the file that you specified in the Input:Key object for this job exceeds the maximum allowed size.
4003 Bad Input File Elastic Transcoder couldn't interpret the file that you specified in one of the Outputs:Watermarks:InputKey objects for this job.
4004 Bad Input File The width x height of a file that you specified in one of the Outputs:Watermarks:InputKey objects for this job exceeds the maximum allowed width x height.
4005 Bad Input File The size of a file that you specified for one of the {1} objects exceeds the maximum allowed size: bucket={2}, key={3}, size{4}, max size={5}.
4006 Bad Input File Elastic Transcoder could not transcode the input file because the format is not supported.
4007 Unhandled Input File Elastic Transcoder encountered a file type that is generally supported, but was unable to process the file correctly. This error automatically opened a support case, and we have started to research the cause of the problem.
4008 Bad Input File

The underlying cause of this is a mismatch between the preset and the input file. Examples include:

  • The preset includes audio settings, but the input file lacks audio.

  • The preset includes video settings, but the input file lacks video.

4009 Bad Input File Elastic Transcoder was unable to insert all of your album art into the output file because you exceeded the maximum number of artwork streams.
4010 Bad Input File Elastic Transcoder could not interpret the graphic file you specified for AlbumArt:Artwork:InputKey.
4011 Bad Input File Elastic Transcoder detected an embedded artwork stream, but could not interpret it.
4012 Bad Input File The image that you specified for AlbumArt:Artwork exceeds the maximum allowed width x height: 4096 x 3072.
4013 Bad Input File The width x height of the embedded artwork exceeds the maximum allowed width x height: 4096 x 3072.
4014 Bad Input The value that you specified for starting time of a clip is after the end of the input file. Elastic Transcoder could not create an output file.
4015 Bad Input Elastic Transcoder could not generate a manifest file because the generated segments did not match.
4016 Bad Input Elastic Transcoder could not decrypt the input file from {1} using {2}.
4017 Bad Input The AES key was encrypted with a {2}-bit encryption key. AES supports only 128-, 192-, and 256-bit encryption keys. MD5={1}.
4018 Bad Input Elastic Transcoder was unable to decrypt the ciphered key with MD5={1}
4019 Bad Input Elastic Transcoder was unable to generate a data key using the KMS key ARN {0}.
4020 Bad Input Your key must be 128 bits for AES-128 encryption. MD5={1}, {2} bits.
4021 Bad Input Your key must be 128 bits for PlayReady DRM. MD5={1}, strength={2} bits.
4022 Bad Input The combined size of the {1} specified media files exceeds the maximum allowed size: bucket={2}, size={3}.
4023 Bad Input The {1} input files specified for concatenation will not create an output with a consistent resolution with the specified preset. Use a preset with different PaddingPolicy, SizingPolicy, MaxWidth, and MaxHeight settings.
4024 Bad Input The {1} input files specified for concatenation will not create thumbnails with a consistent resolution with the specified preset. Use a preset with different thumbnail PaddingPolicy, SizingPolicy, MaxWidth, and MaxHeight settings.
4025 Bad Input At least one media file (input #{1}) doesn't match the others. All media files must have either video or no video.
4026 Bad Input At least one media file (input #{1}) doesn't match the others. All media files must have either audio or no audio.
4100 Bad Input File Elastic Transcoder detected an embedded caption track but could not interpret it.
4101 Bad Input File Elastic Transcoder could not interpret the specified caption file for Amazon S3 bucket={1}, key={2}.
4102 Bad Input File Elastic Transcoder could not interpret the specified caption file since it was not UTF-8 encoded: Amazon S3 bucket={1}, key={2}.
4103 Bad Input File Elastic Transcoder was unable to process all of your caption tracks because you exceeded {1}, the maximum number of caption tracks.
4104 Bad Input File Elastic Transcoder could not generate a master playlist because the desired output contains {1} embedded captions, when the maximum is 4.
4105 Bad Input File Elastic Transcoder cannot embed your caption tracks because frame rate {1} is not supported for CEA-708 - only frame rates [29.97, 30] are supported.
4106 Bad Input File Elastic Transcoder cannot embed your caption tracks because format {1} supports only {2} caption track(s).
9000 Internal Service Error
9001 Internal Service Error
9999 Internal Service Error

Catching Errors

For your application to run smoothly, you need to build in logic to catch and respond to errors. One typical approach is to implement your request within a try block or if-then statement.

The AWS SDKs perform their own retries and error checking. If you encounter an error while using one of the AWS SDKs, you should see the error code and description. You should also see a Request ID value. The Request ID value can help troubleshoot problems with Elastic Transcoder support.

The following example uses the AWS SDK for Java to delete an item within a try block and uses a catch block to respond to the error. In this case, it warns the user that the request failed. The example uses the AmazonServiceException class to retrieve information about any operation errors, including the Request ID. The example also uses the AmazonClientException class in case the request is not successful for other reasons.

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()); }

Error Retries and Exponential Backoff

Numerous components on a network, such as DNS servers, switches, load balancers, and others can generate errors anywhere in the life of a given request.

The usual technique for dealing with these error responses in a networked environment is to implement retries in the client application. This technique increases the reliability of the application and reduces operational costs for the developer.

Each AWS SDK supporting Elastic Transcoder implements automatic retry logic. The AWS SDK for Java automatically retries requests, and you can configure the retry settings using the ClientConfiguration class. For example, in some cases, such as a web page making a request with minimal latency and no retries, you might want to turn off the retry logic. Use the ClientConfiguration class and provide a maxErrorRetry value of 0 to turn off the retries.

If you're not using an AWS SDK, you should retry original requests that receive server errors (5xx). However, client errors (4xx, other than a ThrottlingException or a ProvisionedThroughputExceededException) indicate you need to revise the request itself to correct the problem before trying again.

Note

If you're polling to determine the status of a request, and if Elastic Transcoder is returning HTTP status code 429 with an error code of Provisioned Throughput Exceeded Exception or Throttling Exception, consider using notifications instead of polling to determine status. For more information, see Notifications of Job Status.

In addition to simple retries, we recommend using an exponential backoff algorithm for better flow control. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. For example, you might let one second elapse before the first retry, four seconds before the second retry, 16 seconds before the third retry, and so on. However, if the request has not succeeded after a minute, the problem might be a hard limit and not the request rate. For example, you may have reached the maximum number of pipelines allowed. Set the maximum number of retries to stop around one minute.

Following is a workflow showing retry logic. The workflow logic first determines if the error is a server error (5xx). Then, if the error is a server error, the code retries the original request.

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