*REST API › Errors*

# `rate_limited`

> HTTP HTTP 429.

HTTP status: `429` · Problem type: `https://docs.filmo.io/errors/rate_limited`

## When it happens

429. The key sent more than 120 requests in the current minute, or, for the three availability queries, more than 30 in the current minute. The response carries `Retry-After`, in seconds (the problem body repeats it in `retryAfter`), and the `RateLimit-*` headers say which quota ran out. A 401 and a [`insufficient_scope`](https://docs.filmo.io/rest-api/errors/insufficient_scope) do not consume quota; every other response of an authenticated key does. Decide on any 429 by `Retry-After`, not by the body.

## What to do

Wait the number of seconds in `Retry-After`, then resend. To stay below the limit, spread requests over the minute, page with the largest `limit` you can use, and do not poll a list more often than you need.

## Retry

| Condition | What to do | Note |
| --- | --- | --- |
| 429 rate_limited | Wait `Retry-After`, then retry | Wait the seconds in `Retry-After` and retry with the same key. |

## Fields of errors[]

| Name | Type | Description |
| --- | --- | --- |
| `retryAfter` | integer | On `rate_limited`: seconds to wait before retrying, the same value as the `Retry-After` header. |

## Example

*rate_limited*

```json
{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}
```

## Returned by

`rate_limited` can be returned by any operation.

## Through MCP

A tool call that fails comes back with `isError` set and the problem as structured content, with the same `code`.

---

Canonical URL: https://docs.filmo.io/rest-api/errors/rate_limited  
Last updated: 2026-10-25