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 per defecte en crear una clau es controla des de Developers > API Keys > Settings > Default tier, i es pot sobreescriure per clau des del dashboard.

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.

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. Tier per integració

Si tens dues integracions (un dashboard intern + un cron d'exportació), crea dues claus diferents amb tiers dimensionats per a cadascuna. 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. Després de subscriure't a un add-on superior:

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 i el seu tier; gestiona els tiers des del dashboard (Developers > API Keys).