> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godizzy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Simulate 429 Too Many Requests responses to validate your agent's backoff strategy and error handling before hitting real API limits.

Rate limits are one of the most common ways tool calls fail in production. Your payments API, your search provider, your LLM — all of them impose rate limits. If your agent does not handle 429 correctly, it will either hammer the API until it gets blocked or silently drop work.

With GoDizzy, you can return a 429 on every request to a given endpoint, add realistic latency to simulate the delay before a limit is hit, and layer in a proxy fallback for when you are ready to go live — without changing your agent code.

## Set up a 429 mock with latency

<Steps>
  <Step title="Create a routing rule for the tool endpoint">
    In your route collection, create a new routing rule. For a payments tool:

    * **Method:** `POST`
    * **Path:** `/charges`

    Set a high priority (e.g. `100`) so this rule is evaluated first.
  </Step>

  <Step title="Set the action to mock">
    Choose **Mock** as the action.
  </Step>

  <Step title="Configure the 429 response">
    Set **Status** to `429`. Paste the following into the **Body** field:

    ```json mock body theme={null}
    {
      "error": {
        "code": "rate_limit_exceeded",
        "message": "Too many requests. You have exceeded the rate limit for this endpoint.",
        "retry_after": 30
      }
    }
    ```

    In the **Headers** field, add a `Retry-After` header as a JSON object:

    ```json mock headers theme={null}
    {
      "Retry-After": "30",
      "X-RateLimit-Limit": "100",
      "X-RateLimit-Remaining": "0",
      "X-RateLimit-Reset": "1712178030"
    }
    ```

    The `Retry-After` header tells a well-behaved client how many seconds to wait before retrying. Including it in your mock lets you test whether your agent actually reads and respects it.
  </Step>

  <Step title="Add latency to simulate the lead-up to a rate limit">
    Set **Min latency** to `500` ms and **Max latency** to `1500` ms. This randomizes the response time within that range, simulating the variable delay you see in practice before an API enforces its limit.

    <Note>
      Latency is applied per mock rule. GoDizzy picks a random value within the min/max range for each request. This means consecutive calls will not all take the same time, which is more realistic for testing retry behavior.
    </Note>
  </Step>

  <Step title="Add a lower-priority proxy rule as a fallback">
    Create a second routing rule on the same endpoint:

    * **Method:** `POST`
    * **Path:** `/charges`
    * **Priority:** lower than the mock rule (e.g. `10`)
    * **Action:** Proxy

    This rule proxies to your real payments backend. While the high-priority mock rule is active, it never fires. When you are ready to go live, lower the mock rule's priority below the proxy rule (or delete the mock rule), and real traffic flows through — same URL, no agent changes.
  </Step>
</Steps>

### What the agent sees

```http theme={null}
POST /charges HTTP/1.1
Host: your-collection.godizzy.dev
Content-Type: application/json

{
  "amount": 4999,
  "currency": "usd",
  "source": "tok_visa"
}
```

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712178030

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. You have exceeded the rate limit for this endpoint.",
    "retry_after": 30
  }
}
```

## What to test

Run your agent against this mock and observe:

* **Does the agent retry at all?** If it treats 429 like a hard failure and stops, that is a problem.
* **Does it read the `Retry-After` header?** The correct behavior is to wait the specified number of seconds before retrying — not to retry immediately and not to wait an arbitrary amount.
* **Does it implement exponential backoff?** If your agent retries and the next attempt also returns 429, does it double the wait time?
* **Does it cap retries?** Infinite retry loops under a 429 can cause the agent to hang or exhaust resources.
* **Does it surface the error correctly?** If retries are exhausted, the agent should report a clear failure — not silently complete with missing output.

<Tip>
  Use priority to flip between mock and proxy without editing the rule. While the mock 429 rule sits at priority 100 and the proxy rule at priority 10, every charge attempt returns 429. To let real traffic through, set the mock rule's priority to `5` (below the proxy rule). Same URL, instant switch, no agent code changes.
</Tip>

<Warning>
  If your agent does not implement a retry budget (a maximum number of attempts), a persistent 429 mock will cause it to retry indefinitely. This is a good thing to discover in testing, not production.
</Warning>