Updated: April 14, 2023
Key takeaways
Learn to anticipate and resolve common misunderstandings and errors when customers converse with your skill. Ensure the conversation won’t reach a dead end, and, when an error does occur, write responses that clearly explain what went wrong and how Alexa or the customer might resolve it.
Need quick advice?
View the Design checklist for error handling to learn the traits of effective error flows and messaging.
In this article:
Errors and misunderstandings occur even in natural conversation, and you’ll need to anticipate a range of possible mistakes – on the part of your customers and on the part of Alexa or your skill – to ensure a given conversation won’t come to a screeching halt. There are, however, some common patterns in which customers most commonly experience an error.
You can learn more about preventing errors from occurring in the first place …
Checklist for handling errors:
▢ Use plain language and simple prompts to reduce errors
▢ Explain to the customer what went wrong using the best available data
▢ Reiterate the information the skill needs and why it’s needed to continue
▢ Include answers or clarifications that anticipate questions your skill won’t support
▢ Offer a contextually relevant response when the customer asks for help
▢ Don’t blame the customer for errors
▢ Don’t apologize for errors excessively
▢ Don’t imply or promise future functionality
Take escalating steps to resolve an error. A first-time error might have been a simple mistake, such as the customer stopped paying attention and simply needs your skill to repeat the question. If they reach the same error again, they might still be thinking, or they may be confused about their choices or the question the skill asked them, so a second error may require more explanation from the skill. Repeated errors indicate the customer is either in need of additional help, or, in the case a skill repeatedly receives no response form the customer, they’ve abandoned the skill and it should end the session.
Where possible, ask the customer disambiguating questions if the skill needs more information, rather than requiring they provide complete information in a specific format. Allow customers to provide incomplete information, and follow up on it as needed. (“Did you mean 12 noon, or 12 midnight?”)
Listen to the following examples of a skill attempting to resolve errors using (or not using) the methods above, with varying levels of success.
Bad:
Customer: Alexa, ask MyFlightFinder where my flight is.
Alexa: To find your trip with MyFlightFinder, I have a few questions. First, where are you going?
Customer: Melbourne
Alexa: Hmm. I’m not sure about that one. Where are you going?
Customer: Melbourne!
Alexa: Hmm. I’m not sure about that one. Where are you going?
Customer: I’m going to Melbourne, Florida!
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: …
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: …
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: I don’t know.
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: It’s today sometime
Alexa: I’m sorry. You need to tell me your departure date and time. When are you going?
Customer: Nevermind. Exit
A little better:
Customer: Alexa, ask MyFlightFinder where my flight is.
Alexa: To find your trip with MyFlightFinder, I have a few questions. First, where are you going?
Customer: Melbourne
Alexa: I’ll need to know the city and state or province of your destination. Where are you going?
Customer: Melbourne, Florida.
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: …
Alexa: I didn’t catch that. When are you going?
Customer: …
Alexa: I need your departure date and time to find your flight. When are you going?
Customer: It’s today sometime
Alexa: Today at what time?
Customer: I don’t know
Alexa: From which airport are you leaving?
Customer: Seattle
Alexa: I found two flights today from Seatac International Airport to Melbourne, Florida. The first one departs at 12 pm. The Second one departs at 7 pm. Which do you want?
Customer: Oh it’s the one at noon
Alexa: Hmm. I’m not sure about that. I found two flights today from Seatac International Airport to Melbourne, Florida. The first one departs at 12 pm. The Second one departs at 7 pm. Which do you want?
Customer: The first one
Alexa: The flight from Seattle to Melbourne, Florida, leaving today at 12 pm, is delayed. There's no new departure time yet. Want to check another trip?
Best:
Customer: Alexa, ask MyFlightFinder where my flight is.
Alexa: To find your trip with MyFlightFinder, I have a few questions. First, where are you going?
Customer: Melbourne
Alexa: Is that Melbourne in Australia, or Florida?
Customer: In Florida
Alexa: Melbourne, Florida. Got it. When are you going?
Customer: …
Alexa: I didn’t catch that. When are you going to Melbourne, Florida?
Customer: …
Alexa: I didn’t catch that. To find your flight, I’ll need to know a date or time you’ll be going. When are you going to Melbourne, Florida?
Customer: It’s today sometime
Alexa: Ok. Today. Which airport are you leaving from?
Customer: Seattle
Alexa: I found two flights today from Seattle to Melbourne, Florida. The first one departs at 12 pm. The Second one departs at 7 pm. Which do you want?
Customer: Oh it’s the one at noon
Alexa: The flight from Seattle to Melbourne, Florida, leaving today at 12 pm, is delayed. There's no new departure time yet. Want to check another trip?
The “best” error experience above included simple clarifications instead of an error, explained to the customer what went wrong, explained the importance of the information it requested, and allowed the customer say a robust set of utterances and speech patterns to make a request – they weren’t forced to say a specific phrase to continue.
Do:
When a customer asks for help, the skill should offer help with the current task in progress. When they’ve said something your skill doesn’t recognize or makes a request you can’t support, it should provide enough information that the customer can take action right away, change their response, or continue the experience. Include the details of what went wrong and a call to action to resolve it:
- “You’ll need to log in with a MyFlightFinder account …” + “I sent some information to your Alexa App to help you …”
- “I didn’t catch that …” + “When are you going to Melbourne, Florida?”
- “I couldn’t place your order…” + “You can update your payment details on your MyFlightFinder account on the FlightFinder app or myflightfinder dot com.”
Don't:
Don’t play the blame game. Avoid being definitive when (often) the reason for the error isn’t absolutely certain. A skill should neither annoy customers by over-apologizing, nor blame them or use an accusing tone. Also avoid making promises or implying future functionality with your verbiage. Don’t offer to try the action again if the error isn’t likely to be resolved immediately.
- “You don’t have an account yet …” and “That’s not a valid category…”
- “I’m sorry, I can’t search for flights by price yet …”
- “I’m sorry, your payment failed. Do you want to try again?”
Listen to the following example of our hypothetical MyFlightFinder skill varying its error message depending on the type of error and the customer’s context. It will provide relevant help when the customer asks for it (and even when they didn’t have to ask). The designer has also anticipated customers will ask questions related to flights that the skill won’t support. It re-directs the customer to what it can support.
Customer: Alexa, ask MyFlightFinder to find me a flight.
Alexa: To find your trip with MyFlightFinder, I have a few questions. First, where are you going?
Customer: I don’t know. what’s cheap?
Alexa: I can’t search for flight prices, but I can help you track a flight’s status. Where are you going?
Customer: Help
Alexa: I can help you track a flight’s status anywhere in the world. You can ask me for a flight with information like destination, departure time, airport, airline, and more. Where are you going?
Customer: What airline goes to Ireland?
Alexa: I found lots of flights to Ireland. When will you be going?
Customer: I’m going on vacation.
Alexa: Hmm. I’m not sure about that. When will you be going to Ireland?
Customer: I don’t know
Alexa: You can ask me for a date and time, or a time frame, like “next week.” When are you going to Ireland?
Customer: Next year I think
Alexa: I can only find flights departing within the next 90 days. When are you going to Ireland?
Customer: Oh, what’s in the next month?
Alexa: Next month, got it. What city are you leaving from?
Customer: Paris
Alexa: I found a few flights to Ireland, departing Paris, France, next month. The first one is …
Customer: Alexa, I meant Paris, Texas!
Alexa: I found one flight to Ireland, departing Paris, Texas, next month. It departs on January 3 at 4 p.m. Check back withing 72 hours of your flight to get its status. Want to check another trip?
Q: What are some of the most common errors to anticipate?
A: Some of the most common errors your customer may encounter in any given Alexa skill experience include …
| Error | Alexa Response |
|---|---|
| Alexa Speech Recognition (ASR) didn’t register a response from the customer | “I didn’t catch that …” |
| The response from the customer isn’t recognized | “I’m not sure about that …” |
| The customer tried to exceed a limit in their request | “I can only play that sound for up to 90 minutes …” |
| The customer made a request using an utterance or phrase natural to them, but the skill model does not support it | The skill should accept a robust set of utterances a customer might use to make a request. They will use synonyms, partial or incomplete phrases, slang, ordinal numbers, and relative position in a list (“the last one”) to make selections and requests. |
| The customer’s request matched two or more possibilities | “I can find you a flight to Melbourne, in Alaska, or Melbourne, in Australia. Which did you want?” |
| The skill did not support an utterance or speech pattern that the customer is accustomed to using with Alexa | Customers expect a response to requests for help, go back, repeat, or an obvious synonym for the skill’s actual “label” for the function like “Australia” to select “Melbourne, Australia” |
| The customer made a request that requires further action from them | “You’ll need to sign in with a MyFlightFinder account to book a flight …” |
Q: How should a skill handle errors from an Amazon service? Who handles the error?
A: If your skill will have features that require it to hand off to an Amazon-directed experience (a flow handled by Amazon to help the customer complete certain tasks), that experience will usually hand the customer back to your skill when it completes its purpose. If an error has occurred for any reason (a payment failed, for example), you will need to understand what parts of the error that experience will handle, and what parts your skill will handle. You will need to understand what that experience said to the customer already in order to decide how you’ll help them proceed. You can find the technical documentation for those cases in the Amazon Developer Portal developer documentation.
For example, will your skill do any of the following? Here are some examples of important documentation for Alexa technologies and skill types that specify their own set of required edge cases and error handling. They are not comprehensive, but should guide you in your research before you start designing:
| Description | Documents | Sample Edge Case |
|---|---|---|
| Send something to the customer’s phone | Design Guidelines | The customer’s phone is locked vs unlocked; The customer as turned off permission for the skill to send notifications |
| Send the customer notifications | Alexa Skill Development Notifications API Reference | The customer will need to give permission; the skill will need to collect permission to notify during the customer’s Do Not Disturb hours |
| Allow the customer to set a reminder through the skill | Alexa Reminders API Reference | The skill will need to collect permission |
| Allow the customer to make a purchase of goods outside the skill | Amazon Pay for Alexa Skills Overview | The customer may not have any payment information added yet; The customer may have a voice pin set up on their account for purchases; |
| Allow the customer to make a purchase of skill content itself | Understand In-Skill Purchasing tech doc ; Design for In-Skill Purchasing design guidelines | The customer may have in-skill purchasing permissions turned off |