Stage 3 · L09

Explain errors and inspect OpenAPI rather than guessing

Core · original Session 3

An error status tells the caller which boundary rejected an operation. 422 means this request failed declared validation; 404 means the selected resource does not exist; 405 means the method is unsupported for the path; 409 means a valid-shaped write conflicted with a stored constraint. 500 means an unexpected server failure, not a substitute for every expected error.

The checkpoint translates IntegrityError into a small conflict envelope without exposing SQL, a database URL or a driver traceback. This is intentionally broad for the narrow constraints exercised here. A production system should distinguish expected uniqueness conflicts from programming errors and infrastructure failures. Later domain errors make the business vocabulary explicit rather than using arbitrary exception strings.

Inspect /openapi.json and /docs from the running app. The generated schema shows required input fields, additionalProperties=false, response models and the declared 201 response. It derives from the code; editing an informal lesson paragraph does not change it. Conversely, a handler's custom 409 response may need an explicit documentation entry before generated docs fully describe it.

After sending a duplicate Tripod, send a valid GET immediately. A separate request/session must remain usable. The failed request's dependency closes and rolls back its aborted transaction. A test that checks only the 409 text would miss a broken session lifetime or unintended persistent changes.

Use the independent customer failure matrix as transfer evidence: duplicate email409, malformed address422, extra role422, invalid UUID422, unknown UUID404 and one surviving stored customer. No request in this checkpoint sends mail, verifies an address or logs a person in.

400 is a general bad-request outcome; this course's later action-token endpoint uses400 for invalid/replayed tokens. 415 means the endpoint does not accept that media type; the explicit URL-encoded login rejects JSON with415. The stage03 equipment route does not add a manual415 contract, and FastAPI request-validation errors here are422. Inspect each operation's actual contract rather than assuming every endpoint uses the same error for malformed input.

GET /missing → 404
POST to a GET-only route → 405
A declared integer path with word → 422
An explicitly unsupported media type → 415
GET /openapi.json → the registered operation/schema description

OpenAPI describes registered operations; it does not execute a business operation or prove stored state. A stopped server yields a connection failure without an HTTP status; a wrong method yields 405; failed declared integer validation yields 422. A generic internal failure must not disclose driver/private exception text.