What Does Nitter Show for a Rate Limit Error (HTTP 429)?

When Nitter encounters a rate limit error (HTTP 429) from the Twitter API, it renders a dedicated error page displaying "Instance has been rate limited" and provides a hyperlink to alternative public instances.

Nitter is a free and open-source alternative Twitter frontend that respects user privacy by proxying requests. When an instance sends too many requests to Twitter's API, the service receives an HTTP 429 status code. Understanding how Nitter handles these rate limit errors helps administrators diagnose issues and guides users toward available alternative instances.

Detecting the 429 Response in apiutils.nim

Nitter detects rate limiting in src/apiutils.nim by examining raw API responses for the specific string pattern "429 Too Many Requests". When this pattern matches, the system logs the affected session details and raises a RateLimitError exception to interrupt the current request processing.

According to lines 183-184 of src/apiutils.nim, the detection logic captures the URL path and session identifier before propagating the error upward through the application stack:

# src/apiutils.nim (excerpt)

if result.startsWith("429 Too Many Requests"):
  echo "[sessions] 429 error, API: ", url.path,
       ", session: ", session.pretty
  raise newException(RateLimitError, "rate limited")

This early detection ensures that rate-limited responses never reach the content parsing stage, preventing invalid data processing and allowing immediate error handling.

Handling RateLimitError in nitter.nim

The main error response generation occurs in src/nitter.nim, where a dedicated exception handler catches RateLimitError and constructs the user-facing error page. Lines 18-22 define this handler, which utilizes the showError template to return a proper HTTP 429 status code with a helpful message.

The handler dynamically generates a hyperlink using the instancesUrl configuration value, creating a direct escape route for users when the current instance becomes unavailable:

# src/nitter.nim (excerpt)

error RateLimitError:
  const link = a("another instance", href = instancesUrl)
  resp Http429, showError(
    &"Instance has been rate limited.<br>Use {link} or try again later.", cfg)

The a() function creates an HTML anchor tag, while the & string interpolation operator inserts this link into the error message text.

Rendering the Error Page with showError

Nitter generates consistent HTML error pages using the showError template defined in src/routes/router_utils.nim. This utility wraps arbitrary error messages in standard HTML boilerplate, ensuring that the rate limit notification displays correctly across different browsers and device types.

The template accepts the error string and configuration object as parameters, returning a complete HTML document structure:

# src/routes/router_utils.nim (excerpt)

template showError*(error: string; cfg: Config): string =
  ## Returns a full HTML page with the given error message.

  # … (HTML boilerplate) …

  result = "<h1>" & error & "</h1>"

This templating approach keeps error presentation consistent throughout the application while allowing specific handlers like the one in src/nitter.nim to customize the message content.

Configuration for Alternative Instances

The "another instance" hyperlink displayed in the error message derives its destination from the instancesUrl configuration parameter. Typically defined in src/config.nim, this setting allows instance administrators to specify a list of public alternative Nitter instances where users can continue browsing when the current server hits rate limits.

By default, this link points to the official Nitter instances list, but administrators can redirect users to community-specific mirrors or private backup servers as needed.

Summary

• Detection: src/apiutils.nim identifies HTTP 429 responses by checking if results start with "429 Too Many Requests" and raises RateLimitError
• Handling: src/nitter.nim catches the exception and generates a 429 status response using the specific error handler on lines 18-22
• User Experience: The error page displays "Instance has been rate limited" with a clickable link to instancesUrl
• Rendering: The showError template in src/routes/router_utils.nim generates the final HTML structure
• Configuration: The instancesUrl setting controls where the "another instance" hyperlink points

Frequently Asked Questions

What exact message does Nitter display for rate limit errors?

Nitter displays the text: "Instance has been rate limited. Use another instance or try again later." The words "another instance" render as a clickable hyperlink pointing to the configured instancesUrl, allowing immediate navigation to alternative servers.

Which source files are involved in Nitter's HTTP 429 error handling?

Three files coordinate the response: src/apiutils.nim detects the 429 status from Twitter's API, src/nitter.nim contains the RateLimitError handler that formats the user-facing message, and src/routes/router_utils.nim provides the showError template that generates the HTML page structure.

How does Nitter distinguish rate limiting from other API errors?

Nitter specifically checks if the API response string starts with "429 Too Many Requests" in src/apiutils.nim. This string matching approach identifies rate limiting distinctly from other HTTP error codes like 401 (Unauthorized) or 503 (Service Unavailable), ensuring appropriate error handling logic executes.

Can administrators customize the alternative instance link?

Yes. Instance administrators can modify the instancesUrl configuration parameter, typically set in src/config.nim, to point to any URL listing alternative Nitter instances. This allows communities to direct users to specific trusted mirrors or regional servers when the primary instance encounters rate limiting.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}