Límites de frecuencia

Última actualización July 20, 2026

La API está limitada en frecuencia por clave de API (recurriendo a la IP del cliente para una petición no autenticada). Suede fija el límite y la ventana y puede cambiarlos, así que léelos de las cabeceras de la respuesta en lugar de codificar un número fijo.

Cabeceras

Cada respuesta /v1 incluye:

Cabecera	Significado
`X-RateLimit-Limit`	Máximo de peticiones permitidas en la ventana actual.
`X-RateLimit-Remaining`	Peticiones restantes en la ventana actual.
`X-RateLimit-Reset`	Segundo de época Unix en el que se reinicia la ventana.

Cuando superas el límite, la API responde con HTTP 429 y una cabecera Retry-After (segundos que hay que esperar):

JSON

{ "error": { "type": "rate_limited", "message": "Rate limit exceeded. Slow down and retry after the reset.", "request_id": "…" } }

Gestión del 429

Espera y reintenta tras Retry-After segundos. Un patrón sencillo y fiable:

cURL

# Inspecciona tu presupuesto actual a partir de las cabeceras de cualquier respuesta.
curl -sD - -o /dev/null "https://api.suede.io/v1/search?q=test" \
  -H "Authorization: Bearer $SUEDE_API_KEY" | grep -i '^x-ratelimit'

async Task<HttpResponseMessage> GetWithRetryAsync(HttpClient http, string url)
{
    while (true)
    {
        var res = await http.GetAsync(url);
        if (res.StatusCode != System.Net.HttpStatusCode.TooManyRequests) return res;
        var wait = res.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(1);
        await Task.Delay(wait);
    }
}

JavaScript

async function getWithRetry(url, init) {
  for (;;) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("retry-after") ?? "1") * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

La limitación de frecuencia es independiente de la facturación. Consulta Errores para las respuestas 402 que se devuelven cuando tu membresía está inactiva o tu saldo de crédito está vacío.