Límits de peticions

L'API pública aplica dos nivells de quota per garantir l'equitat entre tenants i protegir el backend davant de pics:

1. Quota per minut (finestra lliscant).
2. Quota mensual (calendari natural, es reinicia el dia 1 a les 00:00 Europe/Madrid).

Els límits depenen del tier de la teva API key. El tier es deriva del pla de Factuarea de la teva empresa (o d'un boost de capacitat actiu quan és superior) — mai no es fixa per clau ni per petició, i s'actualitza automàticament quan el teu pla canvia.

Nivells

Els tiers són acumulatius: un cop esgotada la quota mensual reps 429 rate_limit_exceeded fins al dia 1 del mes següent. La quota per minut es reinicia amb una finestra lliscant.

Boost de capacitat

Si necessites més capacitat d'API sense canviar de pla, subscriu-te a un boost de capacitat des del dashboard: un tier estrictament superior al que atorga el teu pla (per exemple, Starter → Pro). Mentre el boost està actiu, totes les teves claus fan servir el tier del boost. Comprar un tier igual o inferior al del teu pla retorna 422 boost_not_applicable.

Finestra lliscant

El cub per minut no és una finestra fixa de "60 segons des de les 12:00". És una finestra lliscant: en qualsevol moment, l'API compta quantes peticions acceptades hi ha en els darrers 60 segons per a la teva clau. Quan el comptador iguala el límit, les peticions següents responen 429 fins que passa prou temps perquè les primeres peticions "surtin" de la finestra.

Capçaleres de resposta

Tota resposta (inclòs 429) inclou:

Exemple de capçaleres en una resposta 200:

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1747314060

I en un 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 7
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747314007

Codi d'error

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has superado el límite de peticiones. Vuelve a intentarlo en unos segundos.",
    "request_id": "req_..."
  }
}

Superar la quota per minut o la mensual respon 429 amb type: rate_limit_error i code: rate_limit_exceeded. La capçalera Retry-After (i el missatge) t'indiquen quant has d'esperar. Els errors d'autenticació repetits es limiten per separat amb code: too_many_auth_failures.

Bones pràctiques

1. Respecta Retry-After

import time, requests

def call_with_retry(url, **kwargs):
    while True:
        resp = requests.get(url, **kwargs)
        if resp.status_code != 429:
            return resp
        sleep = int(resp.headers.get('Retry-After', 1))
        time.sleep(sleep)

2. Back-off exponencial amb jitter

Per a 5xx, on no hi ha Retry-After:

import random, time

def backoff(attempt):
    return min(60, (2 ** attempt) * 0.1 + random.uniform(0, 0.5))

for attempt in range(5):
    resp = requests.get(url)
    if resp.status_code < 500:
        break
    time.sleep(backoff(attempt))

3. Monitoritza X-RateLimit-Remaining

Si la teva integració s'acosta de manera consistent al 10% del límit, considera:

• Pujar de tier.
• Agrupar en lots: en comptes de N POSTs, agrega i fes 1 POST.
• Cachejar lectures freqüents (productes, impostos, sèries).
• Subscriure't a webhooks en comptes de fer polling.

4. Webhooks > polling

Si fas polling de /v1/invoices?status=paid cada minut per detectar pagaments consumeixes 30 rpm només per a això. Subscriu-te a l'esdeveniment invoice.paid i redueix-ho a 0 peticions.

5. Claus per integració

Si tens dues integracions (un dashboard intern + un cron d'exportació), crea dues claus diferents: cada clau té els seus propis cubs per minut i mensual, així un cron pesat no esgota el pressupost d'un dashboard interactiu.

Quotes administratives

Alguns endpoints tenen quotes addicionals independents del rate limit principal:

Aquests límits responen 429 amb type: rate_limit_error i un missatge específic.

Pujada de tier

Canviar de tier no requereix rotar claus. Quan el teu pla canvia (o s'activa un boost de capacitat):

1. Les noves quotes apliquen immediatament.
2. La quota mensual consumida al tier anterior no es reinicia: només creix el topall mensual.
3. Les claus existents conserven el seu id; el nou tier s'aplica a totes automàticament.