An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa for Hospitality, you manage your Echo devices using the Alexa for Hospitality endpoint API. With this API, you can enumerate the devices owned by your Amazon Business account; view and change settings; and associate endpoints with specific rooms.
Enumerate endpoints
Call GET /v2/endpoints?owner=~caller to get the list of endpoints that you registered to your Amazon Business account.
Request format examples
The following examples show how to use this call.
Enumerate endpoints that aren't associated with a unit
The following example lists the endpoints owned by the caller that aren't associated with a unit. By default, the results aren't expanded.
Note: This call only returns endpoints that are not associated with any units. To enumerate endpoints associated with a specific unit, see Enumerate endpoints associated with a unit.
To enumerate endpoints associated with a particular unitId that the caller has permission to access, provide the associatedUnits.id={unitId} parameter.
GET /v2/endpoints?associatedUnits.id={unitId}&expand=all
Filter endpoints to only those endpoints that the caller owns. The only value currently supported is "~caller", that represents the customer information in the bearer token. Note: you must include either the owner filter or the associatedUnits.id filter.
String
Yes (Unless an associatedUnits.id filter parameter is present)
associatedUnits.id
Filter endpoints to only those endpoints that are associated with a particular unit.
String
Yes (Unless an owner filter parameter is present)
nextToken
Token used for getting the next page of results.
String
No
maxResults
Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10.
Integer
No
expand
An attribute (or set of attributes) to include in the response. Current values supported: all, feature:speaker, and feature:connectivity. Note: You can provide multiple values for expand, for example, expand=all&expand=feature.connectivity.
String
No
manufacturer.value.text
Filter endpoints to only those endpoints whose manufacturer.value.text exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, expand=All.
String
No
model.value.text
Filter endpoints to only those endpoints whose model.value.text exactly matches the full text of the specified value.
String Note: To filter on this field, it must be included in the response. For example, expand=All.
No
serialNumber.value.text
Filter endpoints to only those endpoints whose serialNumber.value.text exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, expand=All.
String
No
friendlyName.value.text
Filter endpoints to only those endpoints whose friendlyName.value.text exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, expand=All.
String
No
connections.macAddress
Filter endpoints to only those endpoints whose macAddress exactly matches the specified value. Note: To filter on this field, it must be included in the response. For example, expand=All.
Filter endpoints to only those endpoints whose reachability value exactly matches the specified value. Note: This requires that the feature is expanded, for example, expand=feature:connectivity. For an example of how to use this filter in an API call, see the following request example.
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.
String
Yes
Response body parameters
Field
Description
Type
Required
results
List of endpoints returned in response to the query.
List
Yes
id
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".
String
Yes
manufacturer
The endpoint manufacturer, as a NameValue object.
Object
No
model
The endpoint model, as a NameValue object.
Object
No
serialNumber
The endpoint serial number, as a NameValue object.
Object
No
friendlyName
The friendly name for the endpoint, as a NameValue object.
Object
No
softwareVersion
The software version for the endpoint.
String
No
connections
The methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of connection objects. If no connection is associated with the endpoint, this field is empty.
List
No
features
List of feature objects for this endpoint.
List
No
associatedUnits
List of unit objects for the units that the endpoint is associated with. If the endpoint isn't associated with any units, the list is empty.
List
Yes
operations
List of supported operations.
List
No
paginationContext
Object containing pagination information. If present, the response contains incomplete results. If omitted, all results were already returned.
Object
No
NameValue object
Field
Description
Type
type
The name value type. Currently the only supported value is "PLAIN".
String
value
The name value, as a Value object.
Object
Value object
Field
Description
Type
text
The string value.
String
Connection object
Field
Description
Type
type
The type of connection. Currently the only supported value is TCP_IP.
String
macAddress
The unique identifier for the network interface controller.
String
Feature object
Field
Description
Type
type
The name of the feature, for example, "volume" or "speaker".
String
path
The full path to use for retrieving expand results of this feature, for example, "/v2/endpoints/{endpointID}/features/speaker".
String
Unit object
Field
Description
Type
id
The unit ID, in the format "amzn1.alexa.unit.did.{id}".
String
Pagination context object
Field
Description
Type
nextToken
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results.
The error message for the error. the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503
Service Unavailable
Service is temporarily unavailable.
Manage endpoint-to-unit association
PUT associatedUnits
Call PUT /v2/endpoints/{endpointId}/associatedUnits to update the list of associated units for an endpoint. Currently an endpoint can only be associated with one unit at a time.
Important: The endpoint must have an active connection when changing unit associations.
Note: After the PUT associatedUnits API is called and a 200 code is returned, you should confirm that the endpoint was successfully restarted. See Query the endpoint status.
When you change unit associations for an endpoint, the endpointId might change. Consider using the MAC address or serial number as a secondary, stable identifier during unit transitions.
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".
String
Yes
Request body
[
{
"id": "amzn1.alexa.unit.did.{id}"
}
]
Request body using default unit ID wildcard
[
{
"id": "~caller.defaultUnitId"
}
]
Request body parameters
Field
Description
Type
Required
list of units
The list of units to associate with the endpoint. Each element in the array is a unit ID, in the format "amzn1.alexa.unit.did.{id}". To specify the caller's default unit, use the "~caller.defaultUnitId" wildcard. Currently an endpoint can only be associated with one unit at a time. Note: To remove an endpoint from a unit, associate the endpoint with the caller's default unit.
The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic.
String
No
message
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Type
Message
Description
400
NO_SUCH_UNIT
No such unit
The unit provided in the body does not exist.
400
TOO_MANY_UNIT_ASSOCIATIONS
The request exceeds the maximum number of unit IDs.
The request exceeds the maximum number of unit IDs. Try specifying fewer unit IDs.
400
ENDPOINT_UNREACHABLE
The endpoint is unreachable.
The endpoint is offline. Modifying associatedUnits is not permitted because the device is unreachable.
400
ENDPOINT_NOT_SUPPORTED
Modifying associatedUnits is not supported for this endpoint.
Modifying associatedUnits is not supported for this device type.
400
TOO_FEW_UNIT_ASSOCIATIONS
The request specifies too few unit IDs.
You must provide at least one unit ID.
401
UNAUTHORIZED
Invalid or missing access token
The LWA token is missing, expired, or invalid.
403
FORBIDDEN
Forbidden
The client can list the resource but doesn't have permission to rename the resource.
404
NO_SUCH_ENDPOINT
Endpoint not found
The endpoint in the path doesn't exist, or the client doesn't have permission to list the resource.
429
TOO_MANY_REQUESTS
Too Many Requests
Request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response.
500
INTERNAL_SERVER_ERROR
Internal Service Error
A service error occurred. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-500 response.
503
SERVICE_UNAVAILABLE
Service Unavailable
The service is temporarily unavailable to handle the request.
Query the endpoint status
After you've called the PUT associatedUnits API and received a 200 code, the process to associate the endpoint with the unit is complete on the cloud side. However, the physical endpoint must complete an automatic reboot to complete the endpoint-to-unit association on the endpoint side. There are no steps required to automatically reboot the endpoint.
To check if the endpoint has successfully rebooted, you can poll for the connectivity status of the endpoint. We recommend a polling interval of 2 minutes or greater.
When this API returns an endpointId, the endpoint has successfully rebooted and reconnected to the network.
Important: POST associatedUnits is deprecated. Use PUT associatedUnits instead.
Call POST /v2/endpoints/{endpointId}/associatedUnits to associate an endpoint with a unit. An endpoint can only be associated with one unit at a time.
Important: The endpoint must have an active connection when changing unit associations.
Note: After the associate API is called and a 200 code is returned, you should confirm that the endpoint was successfully restarted. See Query the endpoint status.
When you change unit associations for an endpoint, the endpointId might change. Consider using the MAC address or serial number as a secondary, stable identifier during unit transitions.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503
Service Unavailable
Service is temporarily unavailable.
DELETE associatedUnits
Important: DELETE associatedUnits is deprecated. Use PUT associatedUnits instead.
Call DELETE /v2/endpoints/{endpointId}/associatedUnits/{unitId} to disassociate an endpoint from a unit.
Important: The endpoint must have an active connection when changing unit associations.
Note: After the disassociate API is called and a 200 code is returned, you should confirm that the endpoint was successfully restarted. See GET features/connectivity.
When you change unit associations for an endpoint, the endpointId might change. Consider using the MAC address or serial number as a secondary, stable identifier during unit transitions.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503
Service Unavailable
Service is temporarily unavailable.
Manage connectivity feature
GET features/connectivity
Call GET /v2/endpoints/{endpointId}/features/connectivity to get states and attributes related to connectivity of the endpoint.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503
Service Unavailable
Service is temporarily unavailable.
Manage speaker feature
GET features/speaker
Call GET /endpoints/{endpointID}/features/speaker to retrieve speaker-feature properties, and their corresponding values, of the specified endpoint.
Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.
Field
Description
Type
Required
properties
List of speaker-feature properties, such as volume. Each property object is a polymorphic type. For example, a volume property object represents the state of the endpoint's speaker volume at the time of sample.
List of property objects
Yes
operations
List of objects defining the speaker-feature operations available for the specified endpoint.
List of operation objects
Yes
Property object schema
Field
Description
Type
Required
name
The name of the property. Currently the only supported value is "volume".
String
Yes
value
The current volume, for example, 42. Valid range is from 0 to 100.
Integer
Yes
timeOfSample
The time when the property value was retrieved.
Date
Yes
error
The presence of this field shows that an error occurred during property value retrieval.
Object
No
Error object schema
Field
Description
Type
Required
Type
Type of error encountered during retrieval of speaker property: "DEVICE_UNREACHABLE" or "INTERNAL_ERROR".
String
Yes
message
The name of the property, for example, "volume".
String
Yes
Operation object schema
Field
Description
Type
Required
name
The operation name: "setVolume" or "adjustVolume"
String
Yes
path
The full path that can be used to set some of the speaker-feature properties.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
404
Not found
The requested artifact wasn't found for the client.
429
Too many requests
Request was throttled because the server is too busy.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time.
503
Service Unavailable
Service is temporarily unavailable.
speaker operations
Call POST v2/endpoints/{endpointId}/features/speaker/setVolume to set speaker volume to the specified value on the specified endpoint.
Call POST v2/endpoints/{endpointId}/features/speaker/adjustVolume to adjust speaker volume by the specified value on the specified endpoint.
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".
String
Yes
operation
One of DAAPI operation exposed on the speaker-feature for the specified endpoint: setVolume or adjustVolume.
String
Yes
Request body example for setVolume
{"payload":{"volume":42}}
Request body parameters for setVolume
Field
Description
Type
Required
volume
The absolute volume to set endpoint's speaker volume to. Valid range is 0 to 100.
String
Yes
Request body example for adjustVolume
{"payload":{"volumeDelta":-42}}
Request body parameters for adjustVolume
Field
Description
Type
Required
volumeDelta
The relative volume to adjust the endpoint's speaker volume by. Valid range is -100 to 100. If the volume of the endpoint is already set to '20', and adjustVolume operation is invoked to adjust the endpoint volume by '-30', the endpoint volume is set to 0. Similarly, if the volume of the endpoint is already set to '20' and adjustVolume operation is invoked to adjust the endpoint volume by '90', the endpoint volume is set to 100.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
202
Accepted
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
404
Not found
The requested artifact wasn't found for the client.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time.
503
Service Unavailable
The server is temporarily unavailable.
Get endpoint setting value
You can query the current value of a setting for an endpoint by calling GET /v2/endpoints/{endpointId}/settings/{settingName}.
Get the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
locales
List of locale strings. Up to two locales can be specified. First element in the list is the preferred locale. Not all skill types are available in all locales.
Get the WakeWords setting. This setting controls what alternative wake words can be used to wake up Alexa.
wakeWords
List of wake words, for example, ["ALEXA"]. Alexa supported wake words are ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices support all wake words.
Get the speechConfirmation setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request.
speechConfirmation
The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".
Get the setupModePrivileges setting. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button).
setupModePrivileges
A list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is disabled.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
Get address setting
Call GET /v2/endpoints/{endpointId}/settings/address to get the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.
The city for the endpoint specified in the request.
String
Yes
stateOrRegion
Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries.
String
Yes
districtOrCounty
The district or county associated with the device. This value may be an empty string for non-US countries.
String
Yes
postalCode
The postal code for the endpoint specified in the request.
String
Yes
countryCode
The two-letter country/region code for the endpoint specified in the request.
String
Yes
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
503
Service Unavailable
Service is temporarily unavailable.
Get DoNotDisturb setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb to get the DoNotDisturb setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get Locales setting
Call GET /v2/endpoints/{endpointId}/settings/System.locales to get the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get WakeWords setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords to get the WakeWords setting. This setting controls what alternative wake words the user can say to wake up Alexa.
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.
String
Yes
Response body example
["ALEXA"]
Response body value
A list of the currently enabled wake words, for example, ["ALEXA"]. Alexa supported wake words are, ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices support all wake words.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get SpeechConfirmation setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation to get the end-of-request sound. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa to indicate that Alexa has finished listening to and capturing the request.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get ErrorSuppression setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression to get the list of error suppressions. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested artifact wasn't found for the client.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get SetupModePrivileges setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges to get the list of setup mode privileges. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button).
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.
String
Yes
Response body example
["ALL_SETTINGS"]
Response body value
The list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is disabled.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get MaximumVolumeLimit setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit to get the maximum volume limit.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get TimeZone setting
Call GET /v2/endpoints/{endpointId}/settings/System.timeZone to get the time zone.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get TemperatureUnit setting
Call GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit to get the temperature scale (Celsius or Fahrenheit) setting.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Get DistanceUnits setting
Call GET /v2/endpoints/{endpointId}/settings/System.distanceUnits to get the distance units (Metric or Imperial) setting.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
200
OK
The request succeeded.
204
No content
The setting exists, but it doesn't have a value.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put endpoint setting value
You can update the current value of a setting for an endpoint by calling PUT /v2/endpoints/{endpointId}/settings/{settingName}.
Put the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
locales
List of locale strings. You can specify up to two locales. First element in the list is the preferred locale. Not all skill types are available in all locales.
Put the WakeWords setting. This setting controls what alternative wake words the user can say to wake up Alexa.
wakeWords
List of wake words, for example, ["ALEXA"]. Alexa supported wake words are ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices support all wake words.
Put the speechConfirmation setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request.
speechConfirmation
The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".
Put the setupModePrivileges setting. This setting controls the end user's ability to put the device into configuration mode via the setup mode process (for example, by long-pressing the Action button).
setupModePrivileges
A list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is disabled.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
Post address setting
Call POST /v2/endpoints/{endpointId}/settings/address to set the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.
The city for the endpoint specified in the request.
String
Yes
stateOrRegion
Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries.
String
Yes
districtOrCounty
The district or county associated with the device. This value may be an empty string for non-US countries.
String
Yes
postalCode
The postal code for the endpoint specified in the request.
String
Yes
countryCode
The two-letter country/region code for the endpoint specified in the request.
Error response body example: 400 address suggestions
If the request is malformed or is missing any required parameters, the operation returns a list of address suggestions, sorted in descending order of confidence.
{"addressSuggestions":{"items":[{"address":{"addressLine1":"221 Baker Ave","addressLine2":"","addressLine3":"","city":"Sunnyvale","stateOrRegion":"California","districtOrCounty":"","postalCode":"94085","countryCode":"US"}}]},"code":400,"description":"The input address is invalid. Suggested valid addresses are included in the response."}
Error response body example: 400 address errors
If the request is malformed or is missing any required parameters, the operation returns a list of address errors.
{"addressErrors":{"items":[{"code":"FIELD_REQUIRED|FIELD_INVALID","subCode":"ADDRESS_STREET_INCOMPLETE|...","message":"{human-readable message}","element":"ADDRESS_1|ADDRESS_2|...",}]},"code":400,"description":"The input address is invalid. The list of errors is included in the response."}
Address errors object
Parameter
Description
Type
Required
code
Error code
Enum
No
subCode
Additional information about why an address element is invalid.
Enum
No
message
Human-readable message
String
No
element
Address element to which the error applies.
Enum
No
Address error code values
code value
Description
ELEMENT_REQUIRED
A required element is missing. The element name is specified by the element field.
ELEMENT_INVALID
The value in a field is invalid. The element name is specified by the element field.
Address error subCode values
subCode value
Description
ADDRESS_PRIMARY_RANGE_MISSING_OR_INVALID
The address number was not valid.
ADDRESS_STREET_INCOMPLETE
The street address was not complete.
ADDRESS_LINES_JUNK_DATA
The address line field contains junk data.
ADDRESS_FIELD_LENGTH_HIGH
The length of the address field is greater than allowed.
ADDRESS_CITY_INVALID
There is no city of that name in the specified state.
ADDRESS_COUNTY_INVALID
The specified county is incorrect.
ADDRESS_STATE_INVALID
The specified state is incorrect.
ADDRESS_ZIP_INVALID
The specified zip code is incorrect for the specified street, city and/or state.
ADDRESS_STREET_NOT_FOUND
The street was not found in the specified city.
ADDRESS_MULTIBYTE_CHARACTERS
The field has multi-byte characters.
ADDRESS_DOOR_LEVEL_INFO_MISSING
The address door-level info is missing.
FIELD_EMPTY
A required field was empty.
Address element values
Address element
Description
ADDRESS_1
First line of the address.
ADDRESS_2
Second line of the address, if any.
ADDRESS_3
Third line of the address, if any.
STREET_NAME
Street name present in the address.
BUILDING_NUMBER
Building number.
COMPLEMENT
Number for smaller units in a building, such as an apartment number.
NEIGHBORHOOD
Neighborhoods are smaller regions of city.
CITY
City or municipality that contains the address.
STATE
U.S. state or possession that contains the address.
COUNTRY
Country that contains the address.
ZIP
5-digit or 9-digit zip code of the address.
COUNTY
County that contains the address.
COUNTRY_CODE
Country code of the address.
HTTP response codes
Status Code
Name
Description
201
Accepted
The request succeeded.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
503
Service Unavailable
Service is temporarily unavailable.
Put DoNotDisturb setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb to update the DoNotDisturb setting. This call prevents notifications and proactive experiences (calls, etc.) from disturbing the user.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested artifact wasn't found for the client.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put Locales setting
Call PUT /v2/endpoints/{endpointId}/settings/System.locales to update the locale setting. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".
String
Yes
Request body example
["en-US", "es-US"]
Request body value
List of locale strings. Specify at least one and no more than two locales. The first element in the list specifies the preferred locale. The following locales are supported: de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, fr-FR, fr-CA, hi-IN, it-IT, ja-JP, pt-BR. Not all skill types are available in all locales.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put WakeWords setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords to update the WakeWords setting. This setting controls what alternative wake words can be used to wake up Alexa.
The supported wake words are: ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Not all devices support all wake words.
Note: Before you can update the WakeWords setting for a device, you must set the Locales setting. For details, see Put Locales setting.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put SpeechConfirmation setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation to update the end-of-request sound setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa to indicate that Alexa has finished listening to and capturing the request.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put ErrorSuppression setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression to update the list of error suppressions. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested artifact wasn't found for the client.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put SetupModePrivileges setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges to update the list of setup mode privileges. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button).
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".
String
Yes
Request body example
["ALL_SETTINGS"]
Request body value
List of setup mode privileges. Currently the only supported setup mode privilege is ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is to be disabled.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put MaximumVolumeLimit setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit to update the maximum volume limit.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put TimeZone setting
Call PUT /v2/endpoints/{endpointId}/settings/System.timeZone to update the time zone.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put TemperatureUnit setting
Call PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit to update the temperature scale (Celsius or Fahrenheit) setting.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Put DistanceUnits setting
Call PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits to update the distance units (Metric or Imperial) setting.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status Code
Name
Description
204
No content
Setting applied.
400
Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested endpoint wasn't found.
405
Method Not Allowed
The device doesn't support the setting.
429
Too many requests
The request is throttled.
500
Internal Server Error
The request couldn't be handled because of an internal service error.
Deregister endpoint
Call POST /v2/endpoints/{endpointId}/deregister to deregister an endpoint from your Amazon Business account.
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Name
Description
200
OK
The request succeeded.
400
Bad Request
The request is malformed or is missing one or more required parameters.
401
Unauthorized
The access token is missing, expired, or invalid.
403
Forbidden
The access token is valid, but the user doesn't have the needed LWA scope permissions.
429
Too many requests
Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500
Internal Server Error
The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503
Service Unavailable
Service is temporarily unavailable.
Change an endpoint's friendly name
Call POST /v2/endpoints/{endpointId}/friendlyName to change the friendly name for an endpoint. Alexa uses the friendly name for all GUI and VUI experiences. Customers can use the friendly name to control an endpoint, for example, "Alexa, turn on {friendlyName}."
The name value type. Currently the only supported value is "PLAIN".
String
Yes
value
A Value object containing the friendly name for the endpoint.
Value
Yes
Value object
Field
Description
Type
Required
text
The friendly name string. The string must consist of 1 to 128 Unicode (UTF-8) characters and must not contain special characters or punctuation (except for apostrophes). The following rules apply. * Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, or apostrophes. * Names must contain at least one number or letter.
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.
String
Yes
Error response body format
{"type":"{errorType}","message":"{errorMessage}"}
Error response parameters
Field
Description
Type
Required
type
The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic.
String
No
message
The error message for the error. The error message is exposed only for debugging/logging purposes. No business logic should depend on the content of the error message.
String
No
HTTP response codes
Status code
Type
Message
Description
400
INVALID_FRIENDLY_NAME
The input friendly name has the following problems: {problemString}
The request is missing one or more required parameters, or one or more parameter values aren't valid.
400
DUPLICATE_NAME
The input friendly name is already assigned to another device.
Friendly names must be unique.
401
UNAUTHORIZED
Invalid or missing access token
The LWA token is missing, expired, or invalid.
403
FORBIDDEN
Forbidden
The client can list the resource but doesn't have permission to rename the resource.
404
NO_SUCH_ENDPOINT
Endpoint not found
The endpoint in the path doesn't exist, or the client does not have permission to list the resource.
429
TOO_MANY_REQUESTS
Too Many Requests
Request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response.
500
INTERNAL_SERVER_ERROR
Internal Service Error
A service error occurred.
503
SERVICE_UNAVAILABLE
Service Unavailable
The service is temporarily unavailable to handle the request.
Forget endpoint
Call POST /v2/endpoints/{endpointId}/forget to forget an endpoint.
Note: This call only applies to Alexa's representation of the endpoint. It doesn't propagate back to the entity that reported the endpoint to Alexa (for example, a smart home skill). To ensure the endpoint is not automatically reconnected to Alexa, remove it from the reporter. For example, for endpoints that are reported by a manufacturer's smart home skill, remove the endpoint from the manufacturer's app before calling forget.
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.
String
Yes
Error response body format
{"message":"{errorMessage}"}
Error response parameters
Field
Description
Type
Required
message
The error message for the error.
String
No
HTTP response codes
Status code
Name
Description
400
Bad Request
The request is missing one or more required parameters, or one or more parameter values aren't valid.
401
Unauthorized
The LWA token is missing, expired, or invalid.
403
Forbidden
The user doesn't have permission to perform the operation.
404
Not found
The requested resource wasn't found, or the client doesn't have access to it.
429
Too many requests
Request was throttled. Don't perform automatic retries. Wait until the service has recovered, and then retry the operation.
500
Internal Server Error
A service error occurred. Retry after one second, backing off exponentially with jitter until a 256-second wait. Retry every 256 seconds thereafter until you receive a non-500 response.
503
Service Unavailable
The service is temporarily unavailable to handle the request.
