Error Shapes

End-to-end developer runbook

1. Step 1 - Confirm the API area: Identify the product area, route module, endpoint path, and consumer before writing or calling code.
2. Step 2 - Read the endpoint contract: Check method, auth, parameters, response, errors, side effects, and related docs.
3. Step 3 - Prepare authentication and input: Use the right session, bearer token, webhook secret, or internal header. Validate body and query data before sending it.
4. Step 4 - Make the request: Call the endpoint from the correct origin and environment. Keep credentials and secrets out of logs.
5. Step 5 - Verify response, side effects, and records: Confirm status code, response shape, database records, external side effects, and audit evidence.
6. Step 6 - Add tests, docs, and handoff notes: Update route inventory, consumer notes, and certification checks before depending on the change.

Known Worker-level errors

Case	Status	Shape
No route matched	404	{ "error": "Not found" }
Uncaught handler error	500	{ "error": "Internal server error" }

Consumer rules

1. Action 1 - Always check response.ok: Do not assume JSON success.
2. Action 2 - Parse failures defensively: Some endpoints may redirect, stream, or return non-JSON when not yet audited.
3. Action 3 - Preserve status code meaning: UI messages should not collapse auth, validation, not-found, and server errors into one message.
4. Action 4 - Log safely: Do not log secrets, full attendee records, payment details, or sensitive report data.