Pydantic AI · Chapter 9 of 23
Failures and fallbacks
By the end of this chapter you can catch the errors a model's provider sends, read what they say, see the retries that already happen for you, fall back to a second model with FallbackModel, answer a farmer politely when nothing works, and say when to retry and when to fall back. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Real-world agents
- 4 tasks
- Python
- In the all labs plan
The first 2 chapters of Pydantic AI are free. This one comes with the all labs plan.
Why you need this
Tuesday, 7:10 am, the busiest ten minutes of KhetBazaar's day. The model's provider has an outage. Every farmer who writes gets nothing back, and the app's error page shows a Python traceback, in English, to a grape grower in Dindori. Ganesh's phone rings forty times.
Pradnya asks the only question that matters: "Why did a farmer see that?" Kedar has three answers ready. Providers fail, so catch what they send. A second model is cheap insurance, so fall back to it. And when everything fails, say so in words a farmer understands.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
catch_error.py: catch the error and read it
lab-chat-down always answers with an error, as a provider's servers do when they are overloaded. Make an agent for openai-chat:lab-chat-down with the instructions You are KhetBazaar's farmer assistant. and run it on: Can I sell 12 quintal pomegranate at Nashik?
Catch the error and print three lines from it: Status: and its status code, Model: and the model's name, Message: and the message inside the error's body.
- Task 2
fallback.py: a second model when the first is down
Make a FallbackModel that tries openai-chat:lab-chat-down first and openai-chat:lab-chat-mini next, and an agent on it with the instructions You are KhetBazaar's farmer assistant. Run it on: Is there a fee for farm gate collection?
Print the output, then a second line, Answered by: and the name of the model that answered, read from the run's last response.
- Task 3
polite.py: fail politely
Write a function answer(question, model) that returns a reply for a farmer. It runs an agent (instructions You are KhetBazaar's farmer assistant., model settings with a timeout of 2 seconds) on the question, with the model named model for that run (openai-chat: in front), and returns the output.
When the model fails, with an HTTP error or a timeout, it returns exactly: Sorry, I cannot answer right now. Ganesh will call you back.
Catch only the model's errors, not every exception. The Check calls answer with lab-chat, lab-chat-down and lab-chat-slow (which takes 4 seconds).
- Task 4 · interview question
Interview: retry_or_fallback.py, retry or fall back
Ask When will I get paid for my onion? two ways, timing each with time.perf_counter. First, an agent for openai-chat:lab-chat-flaky, retries left as they are. Second, an agent on a FallbackModel from openai-chat:lab-chat-down to openai-chat:lab-chat-mini, with model settings max_retries=0. Both have the instructions You are KhetBazaar's farmer assistant.
Print two lines: Retry: lab-chat-flaky answered in 1.69s, then Fall back: lab-chat-mini answered in 0.15s (the model's name from each run's last response; your seconds, two decimals).
The interviewer will ask: when should KhetBazaar's assistant retry the same model, and when fall back to another? What does each cost?
What you will learn
- What a provider's failure looks like: the HTTP errors, and ModelHTTPError with its status code, model and body.
- The retries that already happen inside the openai client, and max_retries.
- The error family: timeouts are not HTTP errors; ModelAPIError catches both.
- FallbackModel: another model when the first one fails.
- Failing politely, and retry or fall back.
More in Real-world agents
Build "Failures and fallbacks" yourself
KhetBazaar, a Nashik agritech startup, answers farmers on WhatsApp from a bike. You build its farmer assistant. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Pydantic AI are free. This one comes with the all labs plan.