APIs with FastAPI · Chapter 5 of 26

Errors

By the end of this chapter you can choose the right status for a failure (400, 404, 409, 422, 500), raise it on purpose, give the whole API one error shape with exception handlers, rewrite FastAPI's validation errors for people, and answer a crash without telling the world what is inside your server. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: First API
  • 4 tasks
  • FastAPI
  • In the all labs plan

The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.

Why you need this

Every merchant's developer writes code that reads DakiyaGo's errors, and Imran hears what they find. Some errors say {"detail": "..."}, some say {"detail": [...]}, a crash is plain text, and a booking sent twice was simply booked twice: Sunita had two riders at one shop for one parcel. Then, one night when the database was down, a merchant's developer pasted a DakiyaGo error into a public forum, and it held the database's address. An error is part of the API like any answer: it needs the right status, one shape, and nothing secret in it.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    parcels.py: not found, and already booked

    Make an app over parcels.json with two routes. GET /parcels/{awb} answers the parcel as the file holds it, or 404 with a detail naming the AWB. POST /parcels takes merchant_id (M and two digits), order_id (the merchant's own order number, 1 to 40 characters), to_pincode (6 digits) and weight_grams (1 to 30000), and answers 201 with the body plus awb (the next number after the file's highest) and status booked, kept with the others.

    The same merchant_id with the same order_id again answers 409, with a detail naming the AWB that order already has. Another merchant may use the same order_id, and a body that breaks a field's rule still answers 422.

  2. Task 2

    dakiya_error.py: one error shape for the whole API

    Every error should answer {"error": {"code": ..., "message": ...}}. Make an app with a class DakiyaError (an Exception with a status, a code and a message) and an exception handler that answers it in that shape, and two routes: GET /pincodes/{pincode} (the entry from pincodes.json, or 404 with code pincode_not_found) and GET /parcels/{awb} (the parcel from parcels.json, or 404 with code parcel_not_found). Each message names what was not found.

    FastAPI's own errors take the same shape: a path the API does not have answers 404 with code not_found, and a wrong method answers 405 with code method_not_allowed, still with its allow header.

  3. Task 3

    friendly_422.py: a 422 a developer can read

    Make an app with one route: POST /bookings takes merchant_id (M and two digits), drop (name 1 to 60 characters, phone exactly 10 digits, pincode exactly 6 digits) and weight_grams (1 to 30000), and answers the booking back.

    Every validation error answers 422 as {"error": {"code": "invalid_request", "message": ..., "fields": [...]}}, with one entry in fields per problem: field is where it is in the body without the word body, the parts joined with dots (drop.phone, weight_grams), and problem is Pydantic's message for it.

  4. Task 4 · interview question

    Interview: safe_errors.py, when the server breaks

    Make an app with GET /health answering {"status": "ok"}, and a handler so that any crash, in any route, answers 500 with {"error": {"code": "internal", "message": ...}}: plain words of your own, never the exception's text, its type or a traceback. Log the crash at error level with the exception attached, so DakiyaGo can still find out what happened. HTTP errors, such as a 404 for an unknown path, stay what they are.

    The check adds a route of its own to your app that crashes with a secret in its message. The interviewer will ask what a 500 tells an attacker, and what it should say instead.

What you will learn

  • Which status: 400, 404, 409, 422 and 500, and what each tells the client.
  • HTTPException for the failures you expect.
  • Exception handlers: one error shape, for your errors and FastAPI's own.
  • Validation errors rewritten for merchants' developers.
  • A safe 500: a plain message out, the details in your log.

More in First API

Build "Errors" yourself

DakiyaGo, a Jaipur courier startup, takes bookings on WhatsApp. Merchants want an API, and you build it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.