Rate Limits

Cada request de la API de FourA pasa por un rate limit. Encontrará dos tipos de límites: concurrencia (requests simultáneos) y RPM (requests por minuto). Ambos se aplican por servicio.

Cómo funcionan los Rate Limits

La API aplica los límites en dos niveles:

1. Límite global de la API: se aplica a todos los requests independientemente del endpoint. Esta comprobación se ejecuta primero.
2. Límite por servicio: se aplica por separado a cada endpoint (single, proxy, browser). Esta comprobación solo se ejecuta si se pasa el límite global.

Si se alcanza el límite global, la comprobación por servicio no se ejecuta. Un request debe pasar ambas comprobaciones antes de llegar al backend.

Cada nivel realiza un seguimiento de dos métricas:

• Concurrencia: cuántos requests se están ejecutando al mismo tiempo.
• RPM: cuántos requests ha enviado en los últimos 60 segundos.

Respuestas de Rate Limit

Cuando alcanza un límite, la API devuelve una response JSON con su uso actual y los límites vigentes.

429: RPM excedido

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Ha enviado demasiados requests en el último minuto. Espere al periodo retryAfter antes de enviar más.

503: Concurrencia excedida

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Se están ejecutando demasiados requests al mismo tiempo. Algunos de sus requests anteriores aún no han terminado.

Servicio deshabilitado

Cuando un servicio se desconecta temporalmente por mantenimiento, la API devuelve 503 con un mensaje de error diferente:

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

Esto no es un rate limit. El servicio no está disponible temporalmente. Compruebe el valor de retryAfter y vuelva a intentarlo después de esa cantidad de segundos. Esto suele resolverse en cuestión de minutos.

No confunda esto con el 503 de concurrencia. Una response de "Service disabled" no incluirá los campos current o limits.

Campos de la Response

Manejo de Rate Limits

Utilice el campo retryAfter para implementar un backoff:

import requests
import time

def fetch(url, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={"method": "GET", "url": url}
        )

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

Consejos

• Compruebe los campos current en las responses de rate limit para comprender sus patrones de uso.
• Si alcanza constantemente los límites de concurrencia, reduzca el número de requests paralelos.
• Si alcanza los límites de RPM, añada un pequeño retraso entre los requests o agrúpelos en un intervalo de tiempo más largo.
• El valor de retryAfter varía según el tipo de límite: 2 segundos para la concurrencia, 5 segundos para las RPM.
• Una response de "Service disabled" significa que hay un mantenimiento en curso. No siga bombardeando el endpoint.

Relacionado

• API Endpoints: Referencia completa de parámetros
• Error Handling: Todos los tipos de errores y responses
• Troubleshooting: Problemas comunes y soluciones