Amazon AppStream
Developer Guide

This documentation is for an older version of Amazon AppStream. For information about the latest version, see the Amazon AppStream 2.0 Developer Guide.

Handling Errors in Amazon AppStream

When you send requests to and get responses from the Amazon AppStream 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 Amazon AppStream 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, Amazon AppStream 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 Amazon AppStream returns for client and server errors, see API Error Codes (Client and Server Errors).

API Error Codes (Client and Server Errors)

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

A response code of 2xx 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 Amazon AppStream. 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
400 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 Amazon AppStream. 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 Amazon AppStream API was invalid, or the IAM user whose credentials were used for this request is not authorized to perform the operation.

404 ResourceNot Found Exception
  • The specified <resource> could not be found: <resourceId>.

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

Example: You attempted to delete an application that is currently in use. No
429 Limit Exceeded Exception
  • The account already has the maximum number of sessions allowed: account=<accountId>, maximum number of sessions=<maximum>

The current AWS account has exceeded limits on Amazon AppStream objects. .
429 Provisioned Throughput Exceeded Exception You exceeded your maximum allowed provisioned throughput.

Example: Your request rate is too high. The AWS SDKs for Amazon AppStream 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.

429 Throttling Exception Rate of requests exceeds the allowed throughput.

You are submitting requests too rapidly; for example, requests to entitle new sessions.

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 'InstallS3Bucket' failed to satisfy constraint: Member must not be null"}

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 Amazon AppStream support.

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 Amazon AppStream 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.

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.