[codex] Add rate limit documentation (#252)

* Add rate limit documentation

* Fix React return types

* chore(warningInfo): add disclaimer in rate limits

---------

Co-authored-by: raul@facturapi.io <raul@facturapi.io>
Co-authored-by: Raúl García <141654545+raul-facturapi@users.noreply.github.com>

Author: javorosas

website/docs/getting-started/rate-limits.mdx

@@ -0,0 +1,87 @@
+---
+sidebar_position: 6
+---
+
+# Límites de tasa (Rate limits)
+
+Para mantener la API estable para todos, Facturapi aplica límites de tasa y de concurrencia.
+
+Estos límites **pueden cambiar** con el tiempo conforme evoluciona el producto y los patrones de uso.
+Por eso recomendamos diseñar tu integración para tolerar `429 Too Many Requests` de forma explícita.
+
+:::warning Aviso
+Rate limits entrarán en vigor a partir del 19 de Mayo de 2026.
+:::
+
+## Qué puedes esperar
+
+La API aplica políticas distintas según el tipo de operación (por ejemplo):
+
+- Lecturas de detalle.
+- Lecturas con búsqueda/listado.
+- Creación de recursos.
+- Escrituras.
+- Operaciones de escritura más costosas.
+
+Los límites se evalúan por identidad autenticada (organización o usuario). Si una solicitud no incluye una identidad autenticada, se aplica el control por IP.
+
+En entorno test y live aplicamos la misma política de límites para mantener una experiencia consistente durante desarrollo y producción.
+
+:::info
+En condiciones normales de integración no deberías tener problemas con estos límites.
+
+No publicamos umbrales exactos por endpoint para evitar abuso dirigido y preservar la confiabilidad global.
+:::
+
+## Respuesta cuando excediste el límite
+
+Cuando una solicitud excede el límite, la API responde con:
+
+- `429 Too Many Requests`
+- header `Retry-After` (segundos sugeridos antes de reintentar)
+- código de error `RATE_LIMIT_EXCEEDED`
+
+### Ejemplo de manejo de `429`
+
+```javascript
+async function requestWithRetry(call, { maxRetries = 5 } = {}) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await call();
+    } catch (err) {
+      const status = err?.response?.status;
+      if (status !== 429 || attempt === maxRetries) {
+        throw err;
+      }
+
+      const retryAfter = Number(err?.response?.headers?.['retry-after'] || 1);
+      const jitterMs = Math.floor(Math.random() * 250);
+      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000 + jitterMs));
+    }
+  }
+}
+```
+
+## Recomendaciones de integración
+
+### 1) Usa colas para escrituras
+
+Procesa creación de comprobantes con workers y concurrencia controlada, en lugar de disparar ráfagas masivas desde requests web síncronas.
+
+### 2) Implementa backoff exponencial con jitter
+
+Evita reintentos inmediatos y sincronizados. Respeta siempre `Retry-After`.
+
+### 3) Reutiliza recursos ya creados
+
+Guarda `id` de clientes, productos y otros recursos para no recrearlos en cada operación.
+
+### 4) Maneja `429` como parte normal del flujo
+
+Incluye reintentos con backoff y jitter, y respeta siempre `Retry-After`.
+
+## Buenas prácticas operativas
+
+- Incluye y conserva `X-Facturapi-Log-Id` en tu observabilidad para correlacionar incidentes.
+- Define alertas por tasa de `429` y latencia p95/p99.
+- Si tu integración requiere límites más altos, contacta a soporte para incrementarlos para tu organización.

website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/rate-limits.mdx

@@ -0,0 +1,87 @@
+---
+sidebar_position: 6
+---
+
+# Rate limits
+
+To keep the API stable for everyone, Facturapi applies request rate and concurrency limits.
+
+These limits **may change** over time as the product and traffic patterns evolve.
+Because of this, we recommend building your integration to explicitly handle `429 Too Many Requests`.
+
+:::warning Disclaimer
+Rate limits will take effect starting May 19, 2026.
+:::
+
+## What to expect
+
+The API applies different policies depending on the operation type (for example):
+
+- Detail reads.
+- Search/list reads.
+- Resource creation.
+- Writes.
+- Heavier write operations.
+
+Limits are evaluated by authenticated identity (organization or user). If a request does not include an authenticated identity, IP-based limiting is applied.
+
+We apply the same rate-limit policy in test and live mode for a consistent experience across development and production.
+
+:::info
+Under normal integration behavior, you should not run into issues with these limits.
+
+We do not publish exact per-endpoint thresholds to reduce targeted abuse and preserve global reliability.
+:::
+
+## Response when you hit the limit
+
+When a request exceeds the limit, the API returns:
+
+- `429 Too Many Requests`
+- `Retry-After` header (recommended seconds before retrying)
+- `RATE_LIMIT_EXCEEDED` error code
+
+### Example `429` handling
+
+```javascript
+async function requestWithRetry(call, { maxRetries = 5 } = {}) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await call();
+    } catch (err) {
+      const status = err?.response?.status;
+      if (status !== 429 || attempt === maxRetries) {
+        throw err;
+      }
+
+      const retryAfter = Number(err?.response?.headers?.['retry-after'] || 1);
+      const jitterMs = Math.floor(Math.random() * 250);
+      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000 + jitterMs));
+    }
+  }
+}
+```
+
+## Integration recommendations
+
+### 1) Use queues for writes
+
+Process invoice creation with workers and controlled concurrency, instead of sending large synchronous bursts from web requests.
+
+### 2) Implement exponential backoff with jitter
+
+Avoid immediate synchronized retries. Always honor `Retry-After`.
+
+### 3) Reuse previously created resources
+
+Store `id` values for customers, products, and other resources so you do not recreate them on every operation.
+
+### 4) Treat `429` as a normal integration scenario
+
+Include retries with backoff and jitter, and always honor `Retry-After`.
+
+## Operational best practices
+
+- Include and preserve `X-Facturapi-Log-Id` in your observability stack to correlate incidents.
+- Add alerts for `429` rate and p95/p99 latency.
+- If your integration needs higher limits, contact support to increase them for your organization.