Rate limits

The BeeL. API enforces rate limits to protect service stability. Limits are enforced at the network edge, on a fixed 60-second window. What the window is counted against depends on the tier: Standard counts per credential, while Strict and Global count per originating IP address.

Tiers

Client identification

The Standard tier is tracked per credential: per API key, or per client for OAuth2 tokens and dashboard sessions. Each key has its own independent Standard quota, so splitting an integration across several keys (for example one per worker) splits that quota accordingly.

The Strict and Global tiers are tracked per originating IP address, whatever credential you present. Several keys calling from the same host share those two budgets, and adding keys does not raise them.

Excluded endpoints

Response headers

When a rate limit is hit, the API returns 429 Too Many Requests with these headers:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 60

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite global de API excedido. Intenta de nuevo en un minuto."
  }
}

Handling rate limits

Retry with backoff

async function requestWithRetry(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers?.['retry-after'] || '60');
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Best practices

• Use bulk endpoints when operating on multiple resources — one bulk request instead of N individual requests
• Cache responses where possible to avoid unnecessary API calls
• Respect Retry-After headers instead of retrying immediately
• Use idempotency keys so retried requests don't create duplicates

Pacing a polling or reconciliation job

A scheduled job that re-reads invoices — to follow VeriFactu states, or to catch up after a webhook outage — runs under the same Standard budget as the rest of your integration with that key. Keep it well below 300 requests a minute so it never starves your live traffic:

• List, don't fetch one by one. One GET …/invoices?verifactu_status=… page returns many invoices; reading each invoice separately costs one request per invoice.
• Look only where something can still change. An ACCEPTED invoice does not change on its own — see Is ACCEPTED final? — so sweep PENDING, REJECTED and NOT_SUBMITTED, as in Reconcile, do not only listen.
• Prefer webhooks for the fast path. verifactu.status.updated tells you when a record changes; the job is the safety net, and daily is enough for most volumes.
• Give the job its own key if you want its budget separated from your live traffic: the Standard tier counts per credential.
• On a 429, stop and wait Retry-After before the next request.

API status

Check status.beel.es for real-time API uptime, incident reports, and scheduled maintenance.

Need higher limits?

If the standard limits don't fit your use case, contact us and we'll work out a plan:

Related