API Rate Limit Guide

Overview

Rate limiting protects SimBiz 6 API V3 stability, fairness, and security.

It prevents:

• accidental request floods from client bugs/retry loops
• heavy endpoint overuse that degrades performance for others
• abusive write calls on sensitive actions
• noisy-neighbor traffic across shared infrastructure

How Limit Is Applied

Rate limit is evaluated in layers. If any layer exceeds, request is blocked with 429.

Layers:

1. APP layer (per API App)
2. ENDPOINT_GROUP layer (route cost/risk group)
3. ORG layer (optional aggregate tenant cap)
4. IP_FALLBACK layer (optional abuse fallback)

Important:

• Different App IDs are normally counted separately at app layer.
• They can still be constrained together by org/ip layers if configured.

Standard Rate Classes

Class	Purpose	10s	1m	1h
LIGHT_READ	Lightweight reads/health/very simple lookup	40	240	6000
NORMAL_READ	Default read/list APIs	20	120	3000
HEAVY_READ	Reports/expensive reads	5	30	600
WRITE	Normal create/update/delete	10	60	1200
HIGH_RISK_WRITE	Sensitive write actions (void/revoke/cancel etc.)	3	12	120

Limit Exceeded Response

When exceeded:

• HTTP status: 429 Too Many Requests
• key headers:
  • Retry-After
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Response body sample:

{
  "status": "Failed",
  "errors": [
    {
      "code": "V3_RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Please retry later.",
      "details": {
        "scope": "APP",
        "policy_code": "APP_BASELINE_DEFAULT",
        "class_code": "WRITE",
        "window_seconds": 60,
        "limit": 60,
        "current": 61,
        "retry_after_seconds": 14
      }
    }
  ]
}

Integration Best Practices

• Respect 429 and always wait for Retry-After.
• Use exponential backoff + jitter.
• Throttle parallel calls, especially report and write APIs.
• Cache stable reads and avoid duplicate polling.
• Use incremental sync instead of frequent full scans.

Default Endpoint Class Mapping

Below is the current default class map for all registered API V3 endpoints.

Notes:

• This is the default runtime classification.
• Admin can override via endpoint-group policy/rules.

Method	Endpoint	Default Class
DELETE	/api/v3/accounting/journal-entries/{id}	WRITE
DELETE	/api/v3/auth/apps/{app_id}	WRITE
GET	/api/v3/accounting/credit-control/bypass-codes	NORMAL_READ
GET	/api/v3/accounting/journal-entries/{id}	NORMAL_READ
GET	/api/v3/accounting/journal-entries	NORMAL_READ
GET	/api/v3/accounting/reference/accounts	NORMAL_READ
GET	/api/v3/accounting/reference/countries	NORMAL_READ
GET	/api/v3/accounting/reference/currencies	NORMAL_READ
GET	/api/v3/accounting/reports/creditors-aging	HEAVY_READ
GET	/api/v3/accounting/reports/debtors-aging	HEAVY_READ
GET	/api/v3/auth/apps/{app_id}/audit-logs	NORMAL_READ
GET	/api/v3/auth/apps/{app_id}	NORMAL_READ
GET	/api/v3/auth/apps	NORMAL_READ
GET	/api/v3/auth/me/organizations	NORMAL_READ
GET	/api/v3/auth/me/permissions	NORMAL_READ
GET	/api/v3/auth/me	NORMAL_READ
GET	/api/v3/auth/organizations	NORMAL_READ
GET	/api/v3/auth/permissions	NORMAL_READ
GET	/api/v3/business-partners/by-no/{bpartnerNo}	NORMAL_READ
GET	/api/v3/business-partners/groups	NORMAL_READ
GET	/api/v3/business-partners/industries	NORMAL_READ
GET	/api/v3/business-partners/{id}	NORMAL_READ
GET	/api/v3/business-partners	NORMAL_READ
GET	/api/v3/creditor-credit-notes/{id}	NORMAL_READ
GET	/api/v3/creditor-credit-notes	NORMAL_READ
GET	/api/v3/creditor-debit-notes/{id}	NORMAL_READ
GET	/api/v3/creditor-debit-notes	NORMAL_READ
GET	/api/v3/debtor-credit-notes/{id}	NORMAL_READ
GET	/api/v3/debtor-credit-notes	NORMAL_READ
GET	/api/v3/debtor-debit-notes/{id}	NORMAL_READ
GET	/api/v3/debtor-debit-notes	NORMAL_READ
GET	/api/v3/health	LIGHT_READ
GET	/api/v3/inventory/items/by-barcode/{barcode}	NORMAL_READ
GET	/api/v3/inventory/items/by-code/{itemCode}	NORMAL_READ
GET	/api/v3/inventory/items/count	NORMAL_READ
GET	/api/v3/inventory/items/{id}/purchase-list	NORMAL_READ
GET	/api/v3/inventory/items/{id}	NORMAL_READ
GET	/api/v3/inventory/items	NORMAL_READ
GET	/api/v3/inventory/reference-data/{resource}	NORMAL_READ
GET	/api/v3/inventory/reports/stock	HEAVY_READ
GET	/api/v3/inventory/stocks/by-location	NORMAL_READ
GET	/api/v3/official-receipts/{id}	NORMAL_READ
GET	/api/v3/official-receipts	NORMAL_READ
GET	/api/v3/payment-vouchers/{id}	NORMAL_READ
GET	/api/v3/payment-vouchers	NORMAL_READ
GET	/api/v3/purchase-invoices/{id}	NORMAL_READ
GET	/api/v3/purchase-invoices	NORMAL_READ
GET	/api/v3/purchase-orders/{id}	NORMAL_READ
GET	/api/v3/purchase-orders	NORMAL_READ
GET	/api/v3/sales-invoices/{id}	NORMAL_READ
GET	/api/v3/sales-invoices	NORMAL_READ
GET	/api/v3/sales-orders/{id}	NORMAL_READ
GET	/api/v3/sales-orders	NORMAL_READ
GET	/api/v3/support/ticket-priorities	NORMAL_READ
GET	/api/v3/support/ticket-statuses	NORMAL_READ
GET	/api/v3/support/ticket-types	NORMAL_READ
GET	/api/v3/support/tickets/{id}	NORMAL_READ
GET	/api/v3/support/tickets	NORMAL_READ
PATCH	/api/v3/auth/apps/{app_id}	WRITE
PATCH	/api/v3/business-partners/{id}	WRITE
PATCH	/api/v3/inventory/items/{id}	WRITE
PATCH	/api/v3/support/tickets/{id}	WRITE
POST	/api/v3/accounting/credit-control/bypass/check	WRITE
POST	/api/v3/accounting/journal-entries/{id}/confirm	WRITE
POST	/api/v3/accounting/journal-entries/{id}/validate	WRITE
POST	/api/v3/accounting/journal-entries/{id}/void	HIGH_RISK_WRITE
POST	/api/v3/accounting/journal-entries	WRITE
POST	/api/v3/accounting/recurring-invoices/generate	WRITE
POST	/api/v3/auth/apps/{app_id}/reactivate	WRITE
POST	/api/v3/auth/apps/{app_id}/revoke	HIGH_RISK_WRITE
POST	/api/v3/auth/apps/{app_id}/rotate-secret	WRITE
POST	/api/v3/auth/apps/{app_id}/suspend	WRITE
POST	/api/v3/auth/apps	WRITE
POST	/api/v3/auth/token/revoke	HIGH_RISK_WRITE
POST	/api/v3/auth/token	WRITE
POST	/api/v3/business-partners	WRITE
POST	/api/v3/creditor-credit-notes	WRITE
POST	/api/v3/creditor-debit-notes	WRITE
POST	/api/v3/debtor-credit-notes	WRITE
POST	/api/v3/debtor-debit-notes	WRITE
POST	/api/v3/inventory/items	WRITE
POST	/api/v3/official-receipts	WRITE
POST	/api/v3/payment-vouchers/{documentNo}/void	HIGH_RISK_WRITE
POST	/api/v3/payment-vouchers	WRITE
POST	/api/v3/purchase-invoices/{documentNo}/void	HIGH_RISK_WRITE
POST	/api/v3/purchase-invoices	WRITE
POST	/api/v3/purchase-orders	WRITE
POST	/api/v3/sales-invoices/{documentNo}/void	HIGH_RISK_WRITE
POST	/api/v3/sales-invoices	WRITE
POST	/api/v3/sales-orders/{documentNo}/void	HIGH_RISK_WRITE
POST	/api/v3/sales-orders	WRITE
POST	/api/v3/support/tickets/{id}/comments	WRITE
POST	/api/v3/support/tickets/{id}/status	WRITE
POST	/api/v3/support/tickets	WRITE
PUT	/api/v3/auth/apps/{app_id}/organizations	WRITE
PUT	/api/v3/auth/apps/{app_id}/permissions	WRITE