API/Error Handling QA

The route

5 steps to Done

1. 01

   Inventory the API contracts

   Write down what every endpoint promises before testing it.

   Preview prompt + verify gate ▾ Hide ▴

   Produce the API contract inventory: every endpoint with method, path, purpose, auth requirement, request shape, success response (code + body shape), and the expected failure responses (validation 400, unauthorized 401/403, not found 404, conflict 409, server 500). Define the standard error shape all endpoints should return (e.g. {error: {code, message}}). Flag endpoints whose current behavior is unknown.

   • ✓ Every endpoint appears with expected codes
   • ✓ A single error shape is defined
   • ✓ Unknowns are flagged for testing
2. 02

   Test success and failure codes

   Fire real requests: does each endpoint honor its contract?

   Preview prompt + verify gate ▾ Hide ▴

   Test every endpoint with real requests (curl/fetch): the success case (verify code and body shape); invalid input (must be 400 with the standard error shape, not 500 or 200-with-error-string); missing/invalid auth (401/403); nonexistent resources (404, not empty 200 or 500); wrong methods (405 or clean rejection). Record the result matrix endpoint-by-endpoint and fix every deviation, then re-test the fixed ones.

   • ✓ Every endpoint was hit with all scenario classes
   • ✓ No 200s carrying errors remain
   • ✓ Bad input yields 400s, not 500s
3. 03

   Normalize error responses

   One error shape everywhere - safe, consistent, frontend-friendly.

   Preview prompt + verify gate ▾ Hide ▴

   Normalize error handling across the API. Requirements: a global error handler producing the standard shape for all failures; no stack traces, internal paths, or query details in any response (log those server-side instead); consistent codes per failure class; validation errors including field-level details the frontend can render; verify by re-triggering each failure class and diffing the shapes.

   • ✓ Every failure class returns the standard shape
   • ✓ No internals leak in responses
   • ✓ Field-level validation details included
4. 04

   Verify frontend failure handling

   Each failure class needs a visible, correct UI response.

   Preview prompt + verify gate ▾ Hide ▴

   Verify the frontend handles each failure class. Force each against the running app: 400 validation (field errors render at the fields); 401 (redirect to login or session-expired message); 403 (permission message, no crash); 404 (not-found state); 500 (visible error with retry); network-down (offline-style error, no white screen). No failure may produce a silent nothing, an infinite spinner, or a console-only error. Fix gaps and re-force each class.

   • ✓ Each class was forced against the real UI
   • ✓ No silent or console-only failures remain
   • ✓ Retry paths work where offered
5. 05

   Test timeouts and slow paths

   Slowness is a failure mode - bound it and make it recoverable.

   Preview prompt + verify gate ▾ Hide ▴

   Test and fix slow-path behavior. Requirements: client requests have timeouts (define the budget per endpoint type); simulate slow responses (throttle or artificial delay) and verify loading states appear, timeouts trigger with a visible recoverable error, and no double-submits happen when users retry; long-running operations (like generation endpoints) get progress messaging and their own longer budgets; verify the UI never hangs indefinitely on any endpoint.

   • ✓ Timeouts exist with sensible budgets
   • ✓ Slow simulation showed loading then recovery
   • ✓ Retries do not duplicate operations