Skip to content
English - United Kingdom
  • There are no suggestions because the search field is empty.

API Throttle Limits and Rate Limiting

API keys are limited to 50 requests per minute by default. When this limit is exceeded, you'll receive an HTTP 429 error. Implement a 60-second delay before retrying, and use a storage layer rather than querying the API directly in real time.

How rate limiting works

The agentOS API uses a rolling 60-second window for rate limiting. Each request consumes one slot from your allowance, and that slot is replenished exactly 60 seconds after it was used — not all at once at the top of each minute.

Example:

  • 0 seconds — request made → 49 slots remaining
  • 30 seconds — another request made → 48 slots remaining
  • 60 seconds — first slot replenished → 49 slots remaining
  • 90 seconds — second slot replenished → 50 slots remaining

The recommended architecture

The API is not designed for live, real-time data lookups. The correct pattern is:

✅ Recommended: API → Your storage layer → Your application

❌ Avoid: Your application → API (for every data lookup)

Use scheduled jobs to periodically import fresh data from the API into your own database or cache. Your application should then query your storage layer. Direct API calls are acceptable for data submission (e.g. tenancy applications, appointments) but not for data retrieval at scale.

Handling HTTP 429 errors

When you receive a 429 response:

  1. Catch the error — do not terminate execution
  2. Wait 60 seconds before retrying
  3. Resume normal operation after the delay
  4. Repeat as needed

The 60-second wait ensures your full allowance has been replenished before you continue.

Important: Sending repeated requests without delays after receiving 429 errors may be detected as an attack pattern by the load balancer, resulting in HTTP 403 errors and potential temporary blocking of your API key. Always implement proper backoff.

Requesting a rate limit increase

If 50 requests per minute is insufficient for your use case, you can request an increase. Before doing so, your integration must correctly handle HTTP 429 errors — increases will not be approved for integrations that fail to implement proper error handling.

To request an increase, email api@agentos.com with:

  • Last 5 digits of your API key
  • Client company name
  • Import frequency (how often your integration syncs data)
  • Storage layer details (database type, caching system, etc.)
  • How long your full import/sync process takes to run
  • Confirmation that your integration handles 429 errors without failing

Additional charges apply for rate limit increases, billed per additional 50 requests per minute increment.

Optimisation tips

  • Use endpoints that return multiple records at once where available
  • Distribute API calls evenly across time rather than sending in bursts
  • Implement caching to reduce API dependency
  • Use queuing for non-urgent requests