DiseñosEnglish

Límites de uso e idempotencia

Límites de uso

Todos los planes tienen los mismos límites, compartidos por todas las claves de API de tu agencia:

  • 10 solicitudes por segundo en ráfagas y 300 por minuto sostenidas, para todo excepto la ingesta;
  • 60 por minuto para POST /v1/leads:ingest, con un límite propio, para que una carga histórica nunca ralentice tus otras integraciones.

Cada respuesta te dice cómo vas, en el formato de la IETF y en el formato X- habitual:

RateLimit-Policy: "burst";q=10;w=1, "minute";q=300;w=60
RateLimit: "minute";r=287;t=4
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 4

RateLimit y X-RateLimit-* describen el límite más ajustado: r solicitudes restantes y t segundos hasta que se recupere por completo.

Cuando se agota un límite, la respuesta es 429 con Retry-After en segundos. Espera ese tiempo y reintenta; baja el ritmo cuando Remaining esté bajo.

Idempotencia

Las redes fallan a mitad de una solicitud. Para que reintentar un POST sea seguro, envía un header Idempotency-Key: cualquier cadena única de hasta 255 caracteres, como un UUID o el id del registro en tu sistema:

curl https://api.letsrealty.io/v1/leads:ingest \
  -H "Authorization: Bearer $LETSREALTY_API_KEY" \
  -H "Idempotency-Key: crm-export-000123" \
  -H "Content-Type: application/json" \
  -d '{ "source": "CRM anterior", "type": "registration", "person": { "name": "Luis", "phone": "8888 0000" } }'
  • La primera solicitud con una clave se ejecuta normalmente y su respuesta se guarda durante 24 horas.
  • Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada —mismo estado y mismo cuerpo— con Idempotent-Replayed: true. Nada se ejecuta dos veces.
  • Un reintento mientras la primera todavía se ejecuta recibe 409; vuelve a intentarlo en un momento.
  • Reutilizar una clave con un cuerpo distinto recibe 422.
  • Una solicitud que falla la validación no guarda nada, así que puedes corregirla y reenviarla con la misma clave.

Las claves de idempotencia se asocian a la clave de API que las envió. Todos los POST de la API aceptan una.