Límites y paginación

Límite de peticiones

Cada API key tiene su propio contador, separado para lecturas y escrituras:

Tipo	Por defecto
Lecturas (GET)	600 por minuto
Escrituras (POST)	120 por minuto

Consulta los de tu clave en GET /me → limites. Un negocio puede fijar un tope más bajo a una clave concreta desde Configuración → Integraciones.

Cabeceras

Todas las respuestas llevan el estado del contador:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-Request-Id: c0a8f3e2-4b91-4d77-8a1e-9f2c6b5d0e31

Cuando te pasas, 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "error": {
    "code": "rate_limited",
    "message": "Has superado el límite de peticiones de esta clave. Espera y vuelve a intentarlo.",
    "details": { "retry_after_seconds": 23 }
  }
}

Respeta Retry-After. No reintentes de inmediato: solo empeora la espera.

Una clave por sistema

Los contadores son por clave. Si tu ERP y tu tienda comparten una sola clave, compiten por el mismo cupo. Dale una clave a cada sistema: además de repartir el límite, sabrás quién hizo cada petición.

Paginación por cursor

GET /invoices devuelve los resultados en páginas, de la más reciente a la más antigua:

{
  "data": [ { "id": "6f1e…", "estado": "autorizado" } ],
  "next": "https://olympus.atharix.com/api/v1/invoices?cursor=cD0yMDI2LTA5…",
  "previous": null
}

• data: los resultados de esta página.
• next: URL de la siguiente página, o null si no hay más.
• previous: URL de la anterior, o null si estás en la primera.

Sigue next tal cual, sin construir el cursor tú:

def todas_las_facturas(client, **filtros):
    url = "/invoices"
    params = filtros
    while url:
        pagina = client.get(url, params=params).json()
        yield from pagina["data"]
        url = pagina["next"]
        params = None  # La URL de next ya lleva los filtros incorporados.

El tamaño de página es 50 por defecto y admite hasta 200 con ?limit=.

Por qué cursor y no números de página

Con páginas numeradas, una factura emitida mientras recorres el listado desplaza los resultados y puedes leer dos veces la misma o saltarte una. El cursor se ancla a un punto fijo del listado, así que recorrerlo entero es fiable aunque se sigan emitiendo facturas.

Filtros del listado

Parámetro	Ejemplo	Qué hace
estado	?estado=autorizado	Filtra por estado público
desde / hasta	?desde=2026-09-01&hasta=2026-09-30	Rango de fecha de emisión
referencia_externa	?referencia_externa=SO-2026-0912	La venta de tu sistema
secuencial	?secuencial=001-001-000000001	Número completo
identificacion	?identificacion=1792060346001	Comprador
limit	?limit=200	Tamaño de página

Se combinan entre sí: ?estado=no_autorizado&desde=2026-09-01 da las rechazadas de este mes, que es justo lo que querrás revisar cada mañana.

Otros límites

Límite	Valor
Tamaño máximo del cuerpo	1 MB
Longitud de Idempotency-Key	255 caracteres
Destinatarios en un reenvío de correo	5
Retención del registro de peticiones	90 días