# Paginação, idempotência e limites

Percorra listas por página ou cursor, tente de novo sem duplicar e trate o 429.

Guia REST

## Percorra listas por página ou cursor

Todas as listas aceitam page (desde 1) e pageSize, e trazem meta.total e meta.totalPages. Contatos, negócios e tarefas aceitam também cursor: passe o meta.nextCursor da resposta anterior até meta.hasMore ser false. Com includeTotal=false o total não é contado (chega null) e fica mais rápido. O pageSize máximo é 500 em contatos, negócios, tarefas e compromissos, e 48 em imóveis.

Cursor:

```
// Contactos, negocios y tareas: por cursor, sin contar el total (lo más rápido).
async function* all(path, params = {}) {
  let cursor;
  do {
    const qs = new URLSearchParams({ ...params, pageSize: "500", includeTotal: "false",
                                     ...(cursor ? { cursor } : {}) });
    const res = await api(`${path}?${qs}`);
    const { data, meta } = await res.json();
    yield* data;
    cursor = meta.hasMore ? meta.nextCursor : undefined;
  } while (cursor);
}

for await (const contact of all("/contacts", { status: "NEW" })) { /* … */ }
```

Imóveis:

```
// Propiedades: cursor = id de la última recibida; pageSize máximo 48.
let cursor;
while (true) {
  const qs = new URLSearchParams({ pageSize: "48", ...(cursor ? { cursor } : {}) });
  const { data } = await (await api(`/properties?${qs}`)).json();
  if (data.length === 0) break;
  save(data);
  cursor = data[data.length - 1].id;   // meta.total y meta.totalPages llegan en null
  if (data.length < 48) break;
}
```

Páginas:

```
curl -G https://api.bydomu.com/v1/appointments -H "X-API-Key: $BYDOMU_API_KEY" -d page=2 -d pageSize=100
# "meta": { "total": 342, "page": 2, "pageSize": 100, "totalPages": 4 }
```

Em imóveis o cursor é o id do último recebido (não há nextCursor) e não envie includeTotal=false: ali «false» conta como verdadeiro.

## Tente de novo sem duplicar

Envie Idempotency-Key em POST, PATCH, PUT e DELETE: de 8 a 128 caracteres (letras, números e . _ : -), única por operação na sua imobiliária. Durante 24 horas, a mesma chave com o mesmo método, rota e corpo devolve a resposta guardada sem repetir a mudança. Respostas 5xx não são guardadas: você pode tentar de novo com a mesma chave.

```bash
curl -X POST https://api.bydomu.com/v1/contacts \
  -H "X-API-Key: $BYDOMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync:contact:u_123" \
  -d '{"firstName":"Laura","phone":"+573000000001"}'

# 1.ª vez   → 201 · Idempotency-Status: created
# repetida  → 201 · Idempotency-Status: replayed (la misma respuesta, sin crear otro)
# otro body → 409 IDEMPOTENCY_CONFLICT
# en curso  → 409 IDEMPOTENCY_IN_PROGRESS
```

Derive a chave do seu próprio id (crm-sync:contact:u_123) e não da hora: assim uma nova tentativa, mesmo de outro processo, cai na mesma operação.

## Limites por minuto e o 429

Cada chave tem dois baldes por minuto: todas as requisições e, à parte, as escritas. O suporte pode aprovar mais. Há também um teto de escritas por organização (TENANT_RATE_LIMITED).

Chave Limite

Chave publicável `300/min · 60 escritas`

Chave secreta `60/min · 30 escritas`

Chave anterior aos níveis `1000/min`

O que diz Cabeçalho

Teto por minuto da chave `X-RateLimit-Limit`

O que resta neste minuto `X-RateLimit-Remaining`

Segundos até reiniciar `X-RateLimit-Reset`

Teto de escritas (num 429 de escrita) `X-RateLimit-Write-Limit`

Escritas da organização toda `X-Tenant-RateLimit-Remaining`

Segundos para esperar (no 429) `Retry-After`

## Um cliente que tenta de novo direito

Com 429 espere os segundos de Retry-After; com 5xx, espera crescente com um pouco de aleatoriedade. Nunca repita um 4xx diferente de 429: não vai mudar.

Node.js:

```js
import { randomUUID } from "node:crypto";

// Reintenta 429 y 5xx con la MISMA Idempotency-Key: nunca duplica.
export async function api(path, { method = "GET", body, idempotencyKey } = {}) {
  const key = idempotencyKey ?? (method === "GET" ? undefined : randomUUID());
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`https://api.bydomu.com/v1${path}`, {
      method,
      headers: {
        "X-API-Key": process.env.BYDOMU_API_KEY,
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(key ? { "Idempotency-Key": key } : {}),
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt === 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
  }
}
```

Python:

```python
import os, random, time, uuid
import requests

API = "https://api.bydomu.com/v1"

def api(method, path, json=None, idempotency_key=None):
    key = idempotency_key or (None if method == "GET" else str(uuid.uuid4()))
    headers = {"X-API-Key": os.environ["BYDOMU_API_KEY"]}
    if key:
        headers["Idempotency-Key"] = key
    for attempt in range(1, 6):
        res = requests.request(method, API + path, json=json, headers=headers, timeout=30)
        if res.status_code != 429 and res.status_code < 500 or attempt == 5:
            return res
        retry_after = int(res.headers.get("Retry-After", "0") or 0)
        wait = retry_after if retry_after > 0 else min(30, 0.5 * 2 ** attempt)
        time.sleep(wait + random.random() / 4)
```