*API REST › Errores*

# `rate_limited`

> HTTP HTTP 429.

Estado HTTP: `429` · Tipo del problema: `https://docs.filmo.io/errors/rate_limited`

## Cuándo ocurre

429. La clave envió más de 120 peticiones en el minuto actual o, en las tres consultas de disponibilidad, más de 30 en el minuto actual. La respuesta lleva `Retry-After`, en segundos (el cuerpo del problema lo repite en `retryAfter`), y las cabeceras `RateLimit-*` indican qué cuota se agotó. Un 401 y un [`insufficient_scope`](https://docs.filmo.io/es/rest-api/errors/insufficient_scope) no consumen cuota; cualquier otra respuesta de una clave autenticada sí. Decide ante cualquier 429 por `Retry-After`, no por el cuerpo.

## Qué hacer

Espera el número de segundos indicado en `Retry-After` y vuelve a enviar. Para mantenerte por debajo del límite, reparte las peticiones a lo largo del minuto, pagina con el `limit` más grande que puedas usar y no consultes una lista más a menudo de lo necesario.

## Reintento

| Condición | Qué hacer | Nota |
| --- | --- | --- |
| 429 rate_limited | Esperar `Retry-After` y reintentar | Espera los segundos de `Retry-After` y reintenta con la misma clave. |

## Campos de errors[]

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `retryAfter` | integer | En `rate_limited`: segundos que hay que esperar antes de reintentar, el mismo valor que la cabecera `Retry-After`. |

## Ejemplo

*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
}
```

## Lo devuelven

`rate_limited` los puede devolver cualquier operación.

## Por MCP

Una llamada a una herramienta que falla vuelve con `isError` y el problema como contenido estructurado, con el mismo `code`.

---

URL canónica: https://docs.filmo.io/es/rest-api/errors/rate_limited  
Última actualización: 2026-10-25