Límites de solicitudes

Las solicitudes a la API se limitan por clave de API y por grupo de endpoints:

Endpoints	Límite
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 solicitudes / minuto por clave de API (120 / minuto por IP)
POST /v1/detect · POST /v1/detect/file	10 solicitudes / minuto por clave de API (30 / minuto por IP)
POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket por clave de API: ráfaga 60, recarga 1/s (≈60 / minuto sostenido); por cuenta: ráfaga 120, recarga 2/s. La capa de IP permite 180 / minuto. Cada respuesta incluye el encabezado X-RateLimit-Remaining.

Encabezados de respuesta

Los encabezados que recibes dependen de qué capa respondió, y los tres grupos no se comportan igual:

Encabezado	Significado	Cuándo aparece
X-RateLimit-Remaining	Solicitudes (o tokens) restantes en la ventana actual	Todas las respuestas de los tres grupos
X-RateLimit-Limit	El techo que se aplicó	Todas las respuestas generales y de detección, y cada 429 de la capa de IP. Nunca en una respuesta en tiempo real: el tiempo real consume un cubo, así que no hay un techo fijo que informar
Retry-After	Segundos que hay que esperar antes de reintentar	Solo en un 429
X-RateLimit-Reset	Marca de tiempo Unix de cuándo se reinicia la ventana	Solo en un 429 del grupo general o de detección; nunca del tiempo real ni de la capa de IP

X-RateLimit-Remaining es el único encabezado en el que puedes confiar sin condiciones, y el único que el tiempo real informa cuando la llamada tiene éxito.

Cuando recibes un 429

Al superar un límite, la API responde 429 con el encabezado Retry-After (las respuestas en tiempo real también incluyen el campo retry_after). Deténgase el número de segundos indicado y reanude con retroceso exponencial.

{
  "message": "Too many requests. Limit: 60/min."
}

Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0