Límits de peticions

L'API pública avalua tres eixos de quota per garantir l'equitat entre tenants i protegir el backend davant de pics:

1. API key — finestra lliscant per minut i volum mensual.
2. Empresa — l'agregat de totes les claus de l'empresa.
3. Cartera gestionada — l'empresa gestora i totes les filles actives, només quan la credencial pertany a una cartera.

Els límits depenen del tier de la teva API key. El tier es deriva del pla de Factuarea de la teva empresa: mai no es fixa per clau ni per petició, no existeix una compra de capacitat independent i s'actualitza automàticament quan canvia el pla. Només les migracions històriques grandfathered_addon poden conservar un tier superior, i únicament mentre l'empresa mantingui un pla actiu vàlid.

Nivells

Els límits per clau s'apliquen. Els agregats per empresa són presents al contracte i, a la versió entrant de l'aplicació, funcionen en mode d'observació (shadow): mesuren els rebutjos que haurien ocorregut sense retornar 429. No tractis aquest mode com a capacitat contractada; es pot promocionar a aplicació efectiva després de calibrar-lo sense canviar la forma de la petició ni de la resposta.

Les claus fact_test_ continuen consumint la quota per clau, però els eixos agregats d'empresa i cartera ometen les empreses sandbox perquè el trànsit de prova no consumeixi capacitat agregada de producció.

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.

Sostres d'empresa i cartera

Quan els eixos agregats estan en aplicació efectiva, l'API avalua primer la clau, després l'empresa i finalment la cartera gestionada. Un rebuig d'empresa fa servir company_rate_limit_exceeded o company_monthly_quota_exceeded: afegir claus no eleva aquests sostres perquè es compten totes juntes.

Una cartera gestionada té un catàleg pla independent per tier:

El sòl reservat per empresa s'avalua primer. Una filla per sota del seu sòl pot continuar encara que la banda comuna s'hagi exhaurit; la banda comuna no és, per tant, un total absolut de la cartera. La quota mensual no té sòl i agrega tota la cartera. Aquests valors també estan actualment en mode shadow, pendents de calibració amb trànsit real de tancament.

Els rebutjos de cartera fan servir portfolio_rate_limit_exceeded i portfolio_monthly_quota_exceeded. Crear més empreses filles o API keys no eleva un sostre pla de cartera; reparteix la feina en el temps o sol·licita una ampliació auditada per a l'empresa.

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_..."
  }
}

El code estable identifica quin eix aplicat s'ha exhaurit:

Tots fan servir type: rate_limit_error. Respecta Retry-After quan aparegui; els errors de cartera també publiquen l'instant o els segons de reintent a error.details. 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:

• Canviar a un pla amb un tier superior.
• 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 consumeix el cubell de la clau del dashboard.

Separar claus no augmenta la capacitat agregada. Els sostres d'empresa i cartera sumen les claus que corresponguin; fes servir més claus per aïllament i atribució, no per esquivar la quota.

Quotes administratives

Algunes càrregues tenen pressupostos de protecció independents de la taxa de peticions. No consumeixen els cubs de clau/empresa/cartera ni apareixen a X-RateLimit-*:

Aquests codes responen 429 amb type: rate_limit_error; fes servir Retry-After o error.details.retry_at quan existeixin. Canviar de credencial no evita un pressupost d'empresa. Un 402 storage_quota_exceeded diferent indica que l'emmagatzematge persistent agregat de l'empresa és ple i no s'allibera esperant. Els límits de quantitat d'endpoints webhook són capacitat del pla, no un pressupost 429; consulta Preus.

Pujada de tier

Canviar de tier no requereix rotar claus. Quan el teu pla canvia:

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.

Identitat per enviar documents

L’enviament de documents pot requerir identitat acreditada mitjançant una subscripció activa o una identificació censal acceptada. Les empreses gestionades fan servir la identitat de la gestoria. 422 sender_identity_not_verified requereix corregir aquesta identitat; un 429 correspon a un pressupost d’enviament diferent. Consulta enviament de documents.