flowchart TD
A[Receive params] --> B{Validate query}
B -- empty --> E[Return error envelope]
B -- ok --> C[Fetch API key from auth_service]
C --> D[Call external API via httpx]
D -- HTTPStatusError --> E
D -- ok --> F[Map API response -> output schema]
F --> G[Track usage cost via PricingService]
G --> H[Return success envelope]
Decision Logic
Validation:
Branches: <if/else paths inside the handler that change the shape>
Fallbacks:
Error paths: <each catch block, what error string it returns>
Side Effects
Database writes: <table + columns, e.g. api_usage_metrics row per call>