Limits

Rate limits

Two separate budgets, both per company:

Surface	Limit
API-key billing (/api/v1/billing/* with X-Api-Key)	60 calls/min
MCP and agent tools (POST /api/v1/mcp, agent:read keys / OAuth)	120 calls/min

When you exceed a limit, the API responds 429 with the Retry-After header. The two budgets don’t mix: your emission backend doesn’t compete with your MCP-connected agents.

Two details of the key-surface budget that matter in real integrations:

• The limit is per company, not per key: every key of the same company shares the 60/min. If you run N systems with N keys, they split the same budget.
• Maximum payload 2 MiB on POST /billing/dte (~1 MiB on other routes). Over the limit the API responds 413 with the standard JSON envelope (code: PAYLOAD_TOO_LARGE) — reduce the document size (fewer detalle lines or shorter glosas) and retry. Verified live: until 2026-09 this used to be a 502 with an HTML page from the CDN; not anymore.

How to handle it

• The SDK automatically retries 429s with exponential backoff and jitter, respecting the Retry-After header. If the limit persists, you get a RateLimitError with retryAfter:

  import { RateLimitError } from '@simplohq/sdk';
  
  try {
    await simplo.dtes.list();
  } catch (error) {
    if (error instanceof RateLimitError) {
      console.error(`Rate limited. Retry in ${error.retryAfter ?? '?'}s`);
    }
  }

• Batch work should pace itself instead of relying on retries: queue and space out calls — at 60/min per company, a large emission batch needs its own pacing.

• Agents connected via MCP have their own budget (120/min) — they don’t compete with your emission backend.

Pagination limits

limit on list endpoints ranges from 1 to 100 items per page (default 20) — see Pagination.

Related

• Errors — RateLimitError and the retry rules