Zcode Hook — NVIDIA Build 40 RPM Rate Limiter

Stop getting Provider rate limited the model request. when using free NVIDIA Build API with Zcode.

---

The Problem

If you use the free tier of build.nvidia.com in Zcode, you will see this in API settings:

Your API Rate Limit: Up to 40 rpm

rpm = Requests Per Minute. When Zcode runs fast (multiple tool calls in a loop), it fires more than 40 LLM requests per minute and you get:

Provider rate limited the model request.

or

429 Too Many Requests
Your API Rate Limit Up to 40 rpm

Your task fails and you have to retry manually.

The Solution

A simple PreToolUse hook that enforces a sliding-window rate limit before Zcode makes the next model call.

It stores timestamps of the last 60 seconds in ~/.cache/zcode_nvidia_rpm.json. If you already did 38 requests, it sleeps just enough to stay under the limit. No more 429 errors, just a slightly slower agent.

• No proxy needed
• No external dependency, only Python 3
• Works on macOS / Linux
• Safe: it RESPECTS the limit, it does not bypass it (uses 38 instead of 40)

---

Installation

Prerequisites

• Python 3.8+
• Zcode (GUI version for Mac)
• NVIDIA API key from build.nvidia.com

Step 1: Download the hook script

Automatic:

mkdir -p ~/ZcodeRoot/hooks
curl -o ~/ZcodeRoot/hooks/nvidia-ratelimit.py https://raw.githubusercontent.com/YOUR_USERNAME/zcode-nvidia-ratelimit-hook/main/hooks/nvidia-ratelimit.py
chmod +x ~/ZcodeRoot/hooks/nvidia-ratelimit.py

Manual: Copy hooks/nvidia-ratelimit.py from this repo to:

/Users/YOUR_MAC_USERNAME/ZcodeRoot/hooks/nvidia-ratelimit.py

Step 2: Add the Hook in Zcode (GUI)

This is the main part. The tutorial is inside the README so you don't need to search chat.

1. Open Zcode > Settings (gear icon)
2. Go to Hooks from left sidebar
3. Click New hook or Create hook
4. Switch Runner tab to Shell command (see screenshot below)

Fill exactly like this:

Field	Value
Scope	User
Event	PreToolUse
Runner	Shell command
Matcher	Leave empty (to match all tools: Write, Edit, Bash, etc)
Command	python3 /Users/YOURNAME/ZcodeRoot/hooks/nvidia-ratelimit.py
Shell	System default
Run in background	OFF - must be off, otherwise it won't block
Timeout (seconds)	75 - Important! Default 60 will timeout when we sleep 60s
Status message	Checking NVIDIA 40rpm limit...
Custom fields JSON	Leave as is {}

Replace /Users/YOURNAME/ with your real home path. You can find it with echo $HOME in Terminal.

Screenshot reference: Scope=User, Event=PreToolUse, Runner=Shell command

5. Click Save

Done. Now Zcode will automatically sleep 1.5-2s between requests when needed.

---

Verification

1. Run any heavy task in Zcode that previously failed with Provider rate limited...
2. You should see status Checking NVIDIA 40rpm limit... in Zcode's footer when it throttles
3. Check the log file:

cat ~/.cache/zcode_nvidia_rpm.json

You will see timestamps of recent requests.

Configuration

Open ~/ZcodeRoot/hooks/nvidia-ratelimit.py and edit:

MAX_RPM = 38  # Lower to 30 if you still get rate limited
WINDOW = 60   # 60 seconds sliding window

Why 38 and not 40? To have a safety margin. NVIDIA counts a bit differently on server side.

Simple alternative (no Python)

If you don't want the Python script, you can just put this in Command field:

sleep 2

This limits you to ~30 RPM. Simple but slower.

FAQ

Q: I still get Provider rate limited the model request. A: Lower MAX_RPM to 30, and make sure Run in background is OFF and Timeout is 75.

Q: Does this work for other providers? A: Yes, change MAX_RPM to your provider's limit. Works for any OpenAI-compatible API.

Q: Does this bypass NVIDIA's limit? A: No. It respects the limit by slowing you down. It does not use multiple keys or any bypass trick.

Q: What's the difference between PreToolUse and UserPromptSubmit? A: PreToolUse runs before every tool call (Write, Edit, Bash). Since each tool call triggers one LLM call, throttling tool calls = throttling LLM calls. UserPromptSubmit only runs when you send a message. Use PreToolUse.

Contributing

PRs welcome! If you have a better backoff algorithm, open an issue.

License

MIT - Free to use.

---

توضیح فارسی

این هوک مشکل ارور Provider rate limited the model request. که موقع استفاده از API رایگان انویدیا (40 درخواست در دقیقه) در Zcode پیش میاد رو حل میکنه. کافیه اسکریپت رو دانلود کنی و طبق آموزش بالا هوک رو اضافه کنی تا دیگه به ریت لیمیت نخوری.