Skip to main content

Rate limits, idempotency, and webhooks

This page summarizes cross-cutting behaviors of the Pro Gateway that matter for reliability and integration design. Numeric defaults can change between releases and deployments-use OpenAPI and your AIS technical contact for the authoritative contract.

Rate limiting​

The gateway ships with adaptive rate limiting to protect authentication endpoints, high-traffic customer routes, analytics, and the rest of the surface. When a limit is exceeded, clients typically receive 429 Too Many Requests (sometimes described as a rate-limit error code in JSON bodies).

What banks should do:

  • Implement exponential backoff and jitter on 429.
  • Separate interactive traffic (dashboards) from batch jobs so bulk work does not starve branch users.
  • Ask AIS for tuned limits or dedicated capacity if you have predictable peaks (month-end portfolio pulls, marketing campaigns, etc.).

Exact requests per second / minute / hour depend on deployment configuration-they are not repeated here as if they were universal constants.

Idempotency (safe retries)​

For mutating HTTP methods (POST, PUT, PATCH), the gateway supports idempotency keys on many routes: clients send X-Idempotency-Key or Idempotency-Key so that retries after timeouts do not accidentally create duplicate loans, payments, or side effects.

Important nuance: full response caching for idempotency is tied to server-side infrastructure in your deployment. If that infrastructure is unavailable, idempotency behavior may degrade (for example keys ignored). Your AIS team confirms what is enabled in your stack.

Always verify idempotency on your critical paths in sandbox before production cutover.

Webhooks (outbound callbacks)​

Supported (Pro Gateway, where enabled):

  • Loan lifecycle webhooks: subscribe to HTTPS callbacks for selected loan status transitions. Subscriptions are managed under /api/v1/webhooks/loan-lifecycle/subscriptions in the published OpenAPI. Deliveries are typically signed (for example HMAC-SHA256 with a header such as X-Pro-Webhook-Signature over the raw JSON body) so your receiver can verify authenticity.
  • Rules / workflow webhooks: a separate family of endpoints exists for rule execution events-see OpenAPI tags for rules webhooks. Use case and enablement are deployment-specific.

Operational notes:

  • Webhook delivery may be disabled or throttled by configuration (for example during incidents or maintenance). Design reconciliation and polling as a safety net, not only push.
  • Your bank must expose a reachable, TLS-terminated receiver URL unless AIS hosts a queue on your behalf (uncommon-confirm).

Not claimed here: arbitrary third-party SaaS connectors, card-network webhooks, or core-banking GL posting-those sit in your integration scope unless explicitly included in your AIS program.

Next: API for bank IT · Back: Overview