Troubleshooting API request errors - Amazon Elastic Compute Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Troubleshooting API request errors

In the Amazon EC2 Query API, errors codes are indicated as being either client or server. Client errors usually occur because there is a problem with the structure, content, or validity of the request. Server errors usually indicate a server-side issue.

For more information about API error codes, see Error Codes.

Query API request rate

We throttle Amazon EC2 API requests for each Amazon account on a per-Region basis to help the performance of the service. We ensure that all calls to the Amazon EC2 API (whether they originate from an application, calls to a command line interface, or the Amazon EC2 console) don't exceed the maximum allowed API request rate. The maximum API request rate may vary across Regions. Note that API requests made by users are attributed to the underlying Amazon Web Services account.

The Amazon EC2 API actions are divided into the following categories:

  • Describe actions, such as DescribeInstances and DescribeVolumes. These requests simply retrieve cached data, so they have the highest request limit.

  • Modify actions, such as RunInstances and CreateVolumes. These requests create or modify resources, so they have a lower request limit than describe calls.

  • The CreateKeyPair, AuthorizeSecurityGroupIngress, and RevokeSecurityGroupIngress actions. These requests take the most time and resource to complete, so they have the lowest request limit.

If an API request exceeds the API request rate for its category, the request returns the RequestLimitExceeded error code. To prevent this error, ensure that your application doesn't retry API requests at a high rate. You can do this by using care when polling and by using exponential backoff retries.

Polling

Your application might need to call an API repeatedly to check for an update in status. Before you start polling, give the request time to potentially complete. When you begin polling, use an appropriate sleep interval between successive requests. For best results, use an increasing sleep interval.

Alternatively, you can use Amazon CloudWatch Events to notify you of the status of some resources; for example, you can use the EC2 Instance State-change Notification event to notify you of a state change for an instance. For more information, see the Amazon CloudWatch Events User Guide.

Retries or batch processing

Your application might need to retry an API request after it fails, or to process multiple resources (for example, all your volumes). To lower the rate of API requests, use an appropriate sleep interval between successive requests. For best results, use an increasing or variable sleep interval.

Calculating the sleep interval

When you have to poll or retry an API request, we recommend using an exponential backoff algorithm to calculate the sleep interval between API calls. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses.

Eventual consistency

The Amazon EC2 API follows an eventual consistency model, due to the distributed nature of the system supporting the API. This means that the result of an API command you run that affects your Amazon EC2 resources might not be immediately visible to all subsequent commands you run. You should keep this in mind when you carry out an API command that immediately follows a previous API command.

For more information, see Eventual consistency in the Amazon EC2 Developer Guide.

Unauthorized operation

By default, users, groups, and roles don't have permission to create or modify Amazon EC2 resources, or perform tasks using the Amazon EC2 API. You must explicitly grant permission through IAM policies. If a user attempts to perform an action for which permission has not been granted, the request returns the following error: Client.UnauthorizedOperation.

This error may occur when a policy is unintentionally restrictive. For example, to allow a user to launch instances into a specific subnet, you need to grant permissions for the following resources by specifying their ARNs in your IAM policy: instances, volumes, AMIs, the specific subnet, network interfaces, key pairs, and security groups. If you omit the permission for volumes, for example, the user is only able to launch an instance from an instance store-backed AMI, as they do not have permission to create the root EBS volume for an EBS-backed instance.

For more information about creating IAM policies for Amazon EC2, see IAM policies for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances.

For more information about which ARNs you can use with which Amazon EC2 API actions, see Actions, resources, and condition keys for Amazon EC2 in the Service Authorization Reference.