Skip to content

HTTP inputs, outputs and errors

A Toolora HTTP contract is defined by its registered route, parameter/body models, dependencies, service or RPC result and error mapping. FastAPI’s generated schema describes declared HTTP shapes; business rules and resource authority also depend on the implementation below that shape.

The committed endpoint-security catalogue records methods, paths and declared policy categories. It does not replace request models, business validation or response semantics. Public MCP tools have a separate tool contract rather than inheriting a similar HTTP route’s schema.

Contract element Owning source Interpretation
Mounted path and method server.py router registration and route decorator Most application routers are under /api; MCP/runtime/internal entries have their own registration
Path/query input Function annotations, Query and domain parsers UUIDs, limits and accepted selections vary by operation
Body input Pydantic operation model and explicit validation Required fields, numeric precision and collection bounds; unknown-field policy depends on the model
Authority Dependencies, dedicated admission and resource checks A valid shape is not permission
Transaction input/result Domain service and database RPC Revision, fingerprint, replay and atomicity semantics
Provider JSON boundary postgrest_payload helpers where used A successful transport must still have the expected row/object/scalar shape
Error result Route exception mapping and shared handlers Status plus detail; provider certainty must be interpreted separately

Some routes declare precise response models; others return typed or dynamic dictionaries, projections, binary responses or per-item receipts. Do not infer a single application-wide result envelope. TypeScript assertions in frontend contracts are not runtime validation of the response.

PUT /api/purchase-costs/{invoice_id}/allocations takes a UUID path and SaveCosts. At this revision, it requires a nonnegative expected_revision, a 32-character lowercase hexadecimal basis_fingerprint, at most 500 allocation rows, and a nullable duplicate target. duplicate_checked defaults to false.

Each row has a 1–100 character source key, a description up to 500 characters, an amount with up to 14 digits and two decimal places, and nullable project/overhead-account UUIDs. Parsing these fields is only the first step: the RPC checks source basis, allowed targets, amounts and duplicate rules. A syntactically valid project ID from another company is still invalid for the operation.

A quote draft uses a different revision contract: its expected update timestamp is parsed by the route and passed with supported fields, line edits and optional recipient replacement. There is no global revision field that a client can copy between APIs.

PostgREST can cap rows independently of a requested range. The shared complete-read helper advances by actual returned rows, uses stable caller-owned ordering and probes its safety boundary. Its defaults are 100 rows per request and a 200,000-row complete-read limit. An exceeded complete-read limit raises rather than presenting partial data as complete.

Other endpoints intentionally page or return bounded projections. Counts, continuation fields and source coverage must be interpreted according to that operation. An empty page is not proof that the entire register is empty. Customer admission uses scalar JSON RPC sets to avoid treating a row-capped authorization result as a complete grant set.

A stale allocation produces 409; invalid domain input commonly produces 422; an out-of-scope invoice can produce 404 without exposing another company’s record. The API’s complete-read failure returns 503 with a request to narrow the query. Shared unhandled failures return a generic 500 detail instead of raw exception contents.

A synthetic client submitting revision 7 with valid row shapes must still handle a concurrent revision 8 and retain its proposal. Reposting with 8 without review is not a schema correction. Error diagnosis distinguishes conflict recovery from provider uncertainty.

The source review identifies these exact models and boundaries. Runtime schema, route tests and database tests each prove their own named inputs; no universal validation or compatibility guarantee is inferred from generated documentation.