---
title: "Realie API Rate Limits, Response Codes, and Retries | Realie"
description: "Realie’s API allows 1,200 requests per minute per IP and returns 429 above it. Which response codes are billed, which to retry with backoff, and how MCP agents receive errors."
canonical: https://www.realie.ai/info/realie-api-rate-limits-and-errors
---

# What are Realie’s API rate limits and response codes, and how should my code or agent retry?

By Realie · Published 2026-11-13

## Quick Answer

Realie’s public API allows 1,200 requests per minute per IP address and returns HTTP 429 above that. Only 200 responses are billed. Retry 429, 503, and 504 with exponential backoff and jitter. Do not blindly retry 400, 401, 403, 404, or 409; they need a changed request, a valid key, or an account fix. Over MCP, credential failures are HTTP 401 and account problems return isError results.

[Read the response codes](https://docs.realie.ai/api-reference/response-codes)

### Summary

Realie’s documentation sets the limit at 1,200 requests per minute; it is enforced per IP address on the public REST API at app.realie.ai/api/public, which the Realie CLI also calls. Enterprise customers can ask support to raise it. The per-minute limit is separate from your plan’s monthly allowance of calls, and only successful 200 responses count against that allowance. Each error code tells your code whether to wait, change the request, or fix the account.

## What is the Realie API rate limit?

The public API allows 1,200 requests per minute from one IP address. A request over the limit gets HTTP 429 with the error “Too many requests” and is not billed. The limit covers the REST endpoints under app.realie.ai/api/public, which the Realie CLI calls too. Enterprise customers can email support@realie.ai to have it raised.

That averages 20 requests a second. Pace bulk jobs at or below that rate instead of sending bursts, and where your workflow allows, use search pages of up to 100 properties rather than one lookup per property.

The per-minute limit is separate from your plan’s monthly allowance of calls. For what each plan includes, see [the pricing page](https://www.realie.ai/pricing).

## Which response codes does the API return, and which are billed?

Only a successful 200 response is billed. Every error, including an empty 404 and a 429, is not billed, so a retry costs time and rate-limit headroom but no calls from your plan.

**Realie public API response codes**

| Code | Meaning | Billed | What to do |
| --- | --- | --- | --- |
| 200 | Success | Yes, one call | Use the response |
| 400 | Missing or invalid parameters | No | Fix the request; the same request fails again |
| 401 | API key missing or invalid | No | Send a valid key in the Authorization header |
| 403 | A billing, card, or subscription condition blocks access | No | Read code and action, resolve it in Billing, then retry |
| 404 | No property matched | No | Check the input or try another lookup |
| 409 | A former parcel number matches more than one parcel | No | Look the property up by its exact address |
| 429 | Over 1,200 requests per minute from your IP | No | Back off with jitter, then retry |
| 500 | Internal server error | No | Retry once; contact support if it persists |
| 503 | Service temporarily unavailable | No | Back off, then retry |
| 504 | Gateway timeout | No | Back off, then retry |

Codes and billing from docs.realie.ai/api-reference/response-codes. The API returns 503 for transient database connectivity errors and query timeouts.

## How should my code retry a 429 or 503?

Treat 429, 503, and 504 as temporary. Wait, then retry with exponential backoff and jitter: about 1 second, then 2, then 4, each plus a random delay so parallel workers do not retry in lockstep. Cap the attempts. On a 429, also lower your concurrency: the limit is per IP address, so every worker behind that address shares it. A 500 is an internal error, not a busy signal: retry it once at most, and contact support if it continues.

```js
const TEMPORARY = [429, 503, 504];

async function realieGet(url, apiKey) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, { headers: { Authorization: 'Bearer ' + apiKey } });
    if (!TEMPORARY.includes(res.status) || attempt === 4) return res;
    const delay = 1000 * 2 ** attempt + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}
```

Do not retry 400, 401, 403, 404, or 409 in a loop. The same request fails the same way until something changes: the parameters, the key, the account, or the lookup you use. A 403 carries code, action, and billing_url fields; branch on code rather than the error text, and show action to whoever manages billing.

## Which limits are applied without an error?

Some out-of-range values are clamped rather than rejected, so read the metadata that comes back. Location search caps radius at 2 miles: a larger radius is reduced to 2, and metadata.radiusMiles shows the value used. A comparables search caps maxResults at 50, radius at 25 miles, and timeFrame at 120 months; its metadata.searchParams applies only the maxResults cap, so a larger radius (listed as radiusMiles) or timeFrame appears there as sent.

Other limits return 400. A v3 owner search where offset plus limit exceeds 200 is rejected, because results are only ordered within the first 200. Property search rejects latitude and longitude parameters and points you to location search. includeExplicitNulls=true returns 400 unless both the account and the data read are on the nested v3 response shape.

## How should an AI agent handle errors from the MCP server or CLI?

The MCP server splits errors by who can fix them. A missing or invalid credential returns HTTP 401 with a WWW-Authenticate header before any tool runs, so the host can start OAuth sign-in. Account problems after a valid sign-in, such as no card on file or an unpaid invoice, come back as a tool result marked isError that carries the same code as the REST 403, so the model can read it and tell the user what to fix.

After sign-in, every failed tool call comes back as an isError result carrying the REST error body, so read the body before deciding: an account denial has a code to explain to the user, an empty lookup says nothing matched, and “Service temporarily unavailable” is temporary, worth one retry after a pause. A 401 is for the host, which signs in again. Batch (array) JSON-RPC bodies are rejected with HTTP 400, so send one request per POST. List tools return at most 10 properties per call; page with cursor or offset.

The Realie CLI prints errors as JSON with an error code and exits with code 1, so an agent running it in a shell can branch on the failure. To choose between the three, see [Should my AI agent use an MCP server, a REST API, or a CLI for property data?](https://www.realie.ai/info/mcp-server-vs-rest-api-for-property-data)

## Sources

- [Response codes (Realie docs)](https://docs.realie.ai/api-reference/response-codes)
- [API FAQ (Realie docs)](https://docs.realie.ai/api-reference/faq)
- [Property data API overview and rate limits (Realie docs)](https://docs.realie.ai/api-reference/property-data)
- [OpenAPI specification](https://docs.realie.ai/api-reference/v3/openapi.json)
- [Realie MCP server documentation](https://docs.realie.ai/realie-mcp-server)
- [Realie CLI documentation](https://docs.realie.ai/realie-cli)
- [Realie pricing](https://www.realie.ai/pricing)

## Frequently asked questions

### What is the Realie API rate limit?

1,200 requests per minute per IP address on the public REST API. Requests over the limit return HTTP 429 and are not billed. Enterprise customers can ask support@realie.ai to raise the limit.

### How do I handle 429 errors from a property API?

Wait, then retry with exponential backoff and jitter, about 1, 2, and then 4 seconds plus a random delay. Cap the attempts and lower your concurrency so all your workers stay under the limit together. On Realie, a 429 is not billed, so a retry costs only time.

### Do failed requests count against my plan?

No. Each Realie plan includes a monthly allowance of calls: Free includes 25, $50/mo includes 1,250, $150/mo includes 6,000, $350/mo includes 30,000, and enterprise pricing at $600/mo includes 100,000. A call is one successful request (HTTP 200). An address or parcelId lookup returns one property, and a REST or CLI search page returns up to 100 parcels, so the $50 plan covers up to 125,000 parcels through search. Failed requests (404/401/403) do not count.

### How should an AI agent retry property API errors?

Retry only temporary failures, HTTP 429, 503, and 504, with backoff. On Realie’s MCP server, a 401 means the host must sign in again, and every other failure is an isError tool result carrying the REST error body: explain an account denial or an empty lookup to the user, and retry “Service temporarily unavailable” once after a pause. CLI errors print as JSON and exit with code 1.

### Can I get a higher rate limit?

Enterprise customers can. Email support@realie.ai, and Realie can raise the per-minute limit. It is separate from your plan’s monthly allowance of calls.

### What does a 409 response mean?

A parcel ID lookup used a former parcel number that more than one parcel once held, so Realie cannot tell which property you mean. The 409 is not billed. Look the property up by its exact address instead of retrying the same parcel number.

## Related Questions

- [How do I integrate a real estate API?](https://www.realie.ai/info/real-estate-api-integration)
- [Should my AI agent use an MCP server, a REST API, or a CLI for property data?](https://www.realie.ai/info/mcp-server-vs-rest-api-for-property-data)
- [What is the Realie MCP server?](https://www.realie.ai/info/realie-mcp-server)
- [What property data API has the lowest latency?](https://www.realie.ai/info/lowest-latency-property-data-api)
- [How do I get comparable sales for an address by API?](https://www.realie.ai/info/comparable-sales-api)
- [How much does a real estate API cost?](https://www.realie.ai/info/real-estate-api-pricing)
