docs: Update PLAN.md and QUESTIONS.md with Hiro API rate limit details

Co-authored-by: aider (openrouter/x-ai/grok-4) <aider@aider.chat>

Author: whoabuddy

docs/PLAN.md

@@ -46,3 +46,11 @@ This plan addresses performance issues in the aibtcdev-cache system under bursty
 - Add HIRO_API_KEYS to wrangler.toml.
 - Test with 30+ mixed requests; verify metrics in logs.
 - Deploy to staging, integrate with frontend for real-world testing.
+
+## Additional Enhancements
+### Integrate Hiro Rate Limit Headers
+- Update StacksApiService to parse response headers (e.g., x-ratelimit-remaining-stacks-minute, ratelimit-remaining) after API calls.
+- Use headers to dynamically adjust TokenBucket (e.g., sync available tokens with remaining counts, respect retry-after).
+- Log header info for monitoring.
+- Align with migration timeline: Use new headers from August 1, 2024; remove legacy support after September 1, 2024.
+- Focus on Stacks-specific headers since this project primarily uses Stacks endpoints.

docs/QUESTIONS.md

@@ -1,9 +1,12 @@
 # Open Questions and Tasks for AIBTCDEV Cache Update
 
-## Open Questions
-- Should src/utils/clarity-responses-util.ts be added to the chat for precise updates to clarity value handling in the Worker's fast-path? (Currently referenced but not edited.)
-- Are there specific Hiro API rate limits (e.g., paid tier) that need config adjustments beyond defaults?
-- How should error handling for key assignment failures (e.g., hash mismatch) be implemented in ContractCallsDO?
+## Resolved Questions
+- Should src/utils/clarity-responses-util.ts be added to the chat for precise updates to clarity value handling in the Worker's fast-path?  
+  **Resolution**: Yes, and it has been added to the chat.
+- Are there specific Hiro API rate limits (e.g., paid tier) that need config adjustments beyond defaults?  
+  **Resolution**: Limits are 500 RPM, but requests should be spaced evenly. New response headers are available for dynamic rate limiting (details in PLAN.md).
+- How should error handling for key assignment failures (e.g., hash mismatch) be implemented in ContractCallsDO?  
+  **Resolution**: Handle with specific ApiError messages, similar to other errors in the system.
 
 ## Tasks
 - Add HIRO_API_KEYS as a secret in wrangler.toml (e.g., "key1,key2,key3,key4,key5").