Handling errors
Add input checks, retries and failure paths to a USSD order-tracking flow, so callers always get a useful screen when something goes wrong.
In this guide you take a simple USSD order-tracking flow and make it survive the three things that go wrong in real use: the caller types something invalid, your API has a brief outage, and the order does not exist. The same techniques apply in chatbot and automation projects.
For what each tool does and when to use it, see Error handling. This page is the worked example.
The finished flow:
Start (Main) ─→ Order number (Intermediary, saves orderNumber)
→ Router "Valid format?"
valid → API "Get order" (Retry: 2 attempts)
success → Status (Last)
failure → Router "Why?"
statusCode is 404 → Not found (Last)
fallback → Unavailable (Last)
fallback → Error "Order numbers have 6 digits" → back to Order numberBefore you start, you need a USSD project and an API endpoint such as GET https://api.example.com/orders/{number} that returns { "status": "Out for delivery" }, and 404 when the order is unknown.
Ask for the order number
Add a Menu named Order number. Set Menu Type to Intermediary, Menu Message to Enter your 6-digit order number:, leave Menu Options empty, and set Output variable to orderNumber. Point an option on your Start menu at it.
Reject invalid input with a Router and an Error node
- Add a Router named Valid format? after Order number.
- Add a path and switch it to Expression, then enter
/^[0-9]{6}$/.test(String(state.orderNumber)). - Turn on the Fallback path. Anything that is not six digits goes there.
- Connect the fallback path to an Error node with the Error Message
Order numbers have 6 digits. Please try again. - Connect the Error node back to Order number.
The Error node's message is shown together with the next screen, so the caller sees the problem and the question again in one step. Write it as an instruction, not a fault report.
Call the API with retries
- Connect the Router's first path to an API node named Get order, with method GET and URL
https://api.example.com/orders/{{state.orderNumber}}. - Set Output variable to
order. - Turn on Retry: Attempts
2, Strategy Fixed, Delay (ms)300. Retries happen on timeouts, network errors and 429 or 5xx responses, not on a 404. - Leave Failure path on, so the node has success and failure handles.
- Connect success to a Last menu named Status with the message
Order {{state.orderNumber}}: {{state.order.status}}.
Keep retries short in USSD. The caller is waiting, and the network ends sessions that take too long.
Tell "not found" apart from "unavailable"
When the request fails, the API node still saves a result to its Output variable, with the HTTP status in statusCode.
- Connect failure to a Router named Why?.
- Add a path where
state.order.statusCodeis (loose ==)404, and connect it to a Last menu:We could not find order {{state.orderNumber}}. Check the number and dial again. - Turn on the Fallback path and connect it to a Last menu:
Order tracking is unavailable right now. Please try again later.
Test every path
In the simulator, try:
12aband12345: you see the Error message with the question again.- A real order number: you reach Status.
- An unknown number: you reach the not-found screen.
- Point Get order at a URL that does not respond: after the retries you reach Unavailable.
Then publish.
Check that it worked
- No input leaves the caller on a blank screen or ends the session without an explanation.
- Every path through both Routers is connected. A Router with an unconnected path cannot be built.
- The loop from Error back to Order number is the only loop, and the caller can leave it by hanging up.
The same pattern in other project types
| Project type | Invalid input | Failed call |
|---|---|---|
| Chatbot | Use a Form node, which checks each answer and asks again, and takes failure after the retries run out | Connect the API node's failure handle to a Reply or a Live Chat handoff |
| Automation | Stop runs you do not want with a Filter | Connect failure to a Messaging alert, and add an error workflow for runs that fail outright. See Error workflows. |