Rate limits

Clear limits for every project.A clear answer when you hit one.

ModelRiver limits how fast each project and each IP address can call the API. When a limit is reached, the API returns 429 and tells you how long to wait.

Start building freeSee limits by plan

How limits work

Two checks run on every API request, before any provider is called.

  1. 01

    Per IP address

    Each request is counted against the IP address it came from, per minute, per hour and per day. This check runs first.

  2. 02

    Per project

    Requests made with a project’s API key are also counted against that project, per minute and per hour.

  3. 03

    A clear 429

    Over a limit, the API returns 429 with a Retry-After header and a header that says whether the IP or the project limit was hit.

The numbers

What you get back

Read the headers to back off and retry. Requests refused by a limit are not logged or counted.

429 response
HTTP/1.1 429 Too Many Requests
retry-after: 60
x-ratelimit-limit: 40
x-ratelimit-remaining: 0
x-ratelimit-limit-type: project

{
  "error": "Rate limit exceeded",
  "message": "Too many requests per minute for this project. Maximum 40 requests per minute allowed on the Free plan. Please wait 60 seconds."
}

  • Know which limit you hit

    The limit-type header says project or ip, so you know whether to spread traffic or upgrade.

  • Wait the right amount

    Retry-After is 60 for a per-minute limit and 3,600 for a per-hour limit.

  • Refused requests are free

    A request turned away by a rate limit never reaches a provider, isn’t logged, and doesn’t count toward your plan.

Good to know

Frequently asked questions

What are the limits on each plan?

Per project: 40 requests a minute and 1,200 an hour on Free, 200 and 10,000 on Pro, 1,000 and 60,000 on Scale. Per IP address: 30, 100 or 300 a minute, with hourly and daily limits too.

What happens when I hit a limit?

The API returns 429 with Retry-After, x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-limit-type headers, plus a message saying which limit was reached.

Do refused requests count toward my plan?

No. Requests refused by a rate limit aren’t sent to a provider, aren’t logged and don’t count.

Why do I hit the limit before the project number?

Traffic from one IP address is limited first, and the per-IP limit is lower than the per-project limit. Spread traffic across servers, or upgrade for higher limits.

Is this the same as the monthly request limit?

No. Rate limits are per minute, hour and day. Your plan’s monthly requests are separate: Free stops at 25,000 a month, while Pro and Scale keep working past their included requests.

Start on the free plan

40 requests a minute per project is plenty to build. Move up when your traffic does.

Start building freeSee limits by plan