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

> Discover what Nitter shows for a rate limit error HTTP 429. Learn how Nitter displays rate limiting and offers alternative instances for uninterrupted access.

- Repository: [Zed/nitter](https://github.com/zedeus/nitter)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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:

```nim

# 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:

```nim

# 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:

```nim

# 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.