The Setup

I run a multi-agent system called Nabster that handles my X/Twitter operations. One of the agents — X Nabster — posts replies, originals, and threads to @NabbilKhan on a schedule. The strategy is 70 tweets per day: 50 replies, 10 originals, the rest in threads and quote tweets. We've been growing steadily — 165 followers to 211 in about two weeks.

The system runs on cron cycles. Every 30 minutes, X Nabster wakes up, reads the current state, finds fresh high-engagement posts to reply to, posts 2-4 replies, updates the counters, and goes back to sleep. Simple. Effective. Until it stopped working.

The Symptom

February 13th. X Nabster posted 12 replies before 8 AM, then stopped. Every cycle after that came back with: “Rate limited. 0 remaining. Resets at 1:45 PM CST.”

Nine consecutive cycles blocked. Zero originals posted all day. Meanwhile, I'm watching the clock and wondering why my carefully designed posting strategy is sitting idle during prime hours.

The Wrong Diagnosis

I checked the official X API rate limit documentation. The docs say:

100 per 15 minutes. We posted 12 tweets. That's nowhere close to 100. So clearly X Nabster is misreading something, right?

I was convinced the agent was confusing the 15-minute endpoint rate limit with some imaginary 24-hour cap. I even had CC Nabster (my coding agent) investigate the “bug.” The diagnosis came back: “There is no code bug. The agent itself is manually writing wrong rate limit data.”

So I “fixed” it. Updated RATE-LIMITS.md to say the limit is 100/15min. Updated all four cron job prompts. Cleared the “false” blocker from x-state.json.

X Nabster immediately wrote it back. Because X Nabster was reading actual API response headers. And I was reading documentation.

The Real Limit

Here's what the X API actually returns on a POST /2/tweets response — including 429 errors:

x-rate-limit-limit: 1080000
x-rate-limit-remaining: 1079998
x-rate-limit-reset: 1771010371
x-app-limit-24hour-limit: 1667
x-app-limit-24hour-reset: 1771011904
x-app-limit-24hour-remaining: 1557
x-user-limit-24hour-limit: 100
x-user-limit-24hour-reset: 1771011904
x-user-limit-24hour-remaining: 0

There it is. x-user-limit-24hour-limit: 100. A per-user, 24-hour rolling window cap of 100 tweets. This limit is not documented on the official rate limits page. It only appears in the response headers themselves.

The actual rate limit structure for POST /2/tweets on the Basic tier ($100/month) is:

Three separate limits. The docs only mention two of them. The one that actually blocks you in practice — the 100/24h per user — is the undocumented one.

Why This Matters

If you're running any kind of automated posting on X's Basic tier, 100 tweets per 24 hours is your hard ceiling per user account. That's a rolling window, not a daily reset. Post 70 tweets between 8 AM and midnight, and you've burned 70 of your 100. The next morning, you can only post 30 until those first tweets start rolling off 24 hours after they were created.

For our strategy of 70 tweets/day, this means:

• →70/day is achievable but leaves only 30 buffer in the rolling window
• →Front-loading is fatal — if you blast 50 tweets in 4 hours, you're locked out for 20
• →Spreading evenly is mandatory — roughly 4-5 tweets per hour across 15 active hours
• →Thread parts count — a 6-part thread eats 6 of your 100

We were front-loading. The early morning engagement cycles were posting aggressively, eating through the budget before peak hours. By the time the 12-1 PM and 5-7 PM windows hit — when engagement is highest — we had nothing left.

The Debugging Timeline

Here's how the whole thing unfolded, because the meta-story of an AI agent debugging an AI agent is worth documenting:

The Lesson

I spent two hours “fixing” something that wasn't broken because I trusted documentation over observed behavior. The agent was reading actual API response headers. I was reading a webpage that turned out to be incomplete.

This is a pattern I've seen repeatedly in production AI systems. The docs say one thing. The API does another. The agent operating at the boundary — the one making real requests and parsing real responses — knows the truth before anyone else in the chain.

Three takeaways:

• 1.Always read the headers. Documentation is a promise. Headers are reality. When they disagree, trust the headers.
• 2.Undocumented limits are real limits. X isn't unique here. Most APIs have enforcement layers that aren't fully documented. The only way to discover them is to hit them and read the response carefully.
• 3.When your agent says something you don't expect, verify before overriding. I overrode X Nabster's correct diagnosis twice before actually checking. The agent had empirical data. I had assumptions. The agent was right.

The Fix

Our adjusted strategy:

• →Daily budget: 100 tweets (hard cap, rolling 24h window)
• →Target: 70 tweets/day (leaves 30 buffer for overlap)
• →Pacing: ~4-5 per hour spread across active hours (7 AM - 10 PM)
• →No front-loading — each engagement cycle posts 2-4, not 10-15
• →Rate limit headers now referenced in every cron job prompt

For Other Developers

If you're building on the X API Basic tier and wondering why you're hitting 429s well under the documented limits, check these headers in your response:

The Free tier is even more restrictive — reports suggest 17-50 tweets per 24 hours depending on the endpoint. Pro tier ($5,000/month) presumably raises these caps, but I haven't verified.

Bottom line: Log every 429 response with its full headers. Build your rate limiter around the actual headers, not the docs. And when your agent tells you something that contradicts the documentation — maybe listen to it first.