SemaiSens API Rate Limits, Quotas, and Backoff Strategies

The SemaiSens API enforces rate limits to ensure fair usage and stable performance for all customers. Limits are applied per API key and measured on a rolling per-minute and per-day basis. If your integration exceeds these limits, the API returns a 429 Too Many Requests response until the window resets.

Limits by Plan

Plan	Requests per Minute	Requests per Day
Free	100	1,000
Pro	500	50,000
Enterprise	Custom	Custom

Enterprise customers can request custom rate limit increases by contacting support@example.com. Include your average and peak request volumes, and a description of your use case.

Rate Limit Headers

Every API response includes the following headers so you can monitor your current consumption programmatically.

Header	Type	Description
`X-RateLimit-Limit`	Integer	The maximum number of requests allowed in the current window for your plan.
`X-RateLimit-Remaining`	Integer	The number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp	The UTC time (as a Unix timestamp) when the current window resets and the counter returns to the full limit.

Exceeding the Rate Limit

When you exceed your limit, the API responds with:

Status: 429 Too Many Requests
Header: Retry-After: <seconds> — the number of seconds to wait before retrying
Body:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your request quota. Retry after 42 seconds.",
    "status": 429
  }
}

Do not retry immediately after receiving a 429. Use the Retry-After value or implement exponential backoff (see below).

Best Practices

Implement exponential backoff — Automatically retry failed requests with increasing delays rather than hammering the API.
Cache responses where possible — Resources like field metadata and imagery source lists change infrequently. Cache them locally and refresh periodically instead of re-fetching on every operation.
Use webhooks instead of polling — Subscribe to webhook events for imagery availability and report completion rather than polling GET endpoints in a loop.
Reduce round trips where possible — For large-scale operations, use range-based query parameters and time-series endpoints to fetch multiple results in a single request. See Bulk Operations below.

Exponential Backoff Example

The following Python function retries a request up to five times with exponentially increasing wait times (1 s, 2 s, 4 s, 8 s, 16 s) when it receives a 429 response.

import time
import requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")

Add a small amount of random jitter to each wait period (e.g., wait = 2 ** attempt + random.uniform(0, 1)) to prevent multiple clients from retrying simultaneously and creating a burst of traffic when the window resets.

Bulk Operations

For high-volume workflows such as ingesting large field portfolios or requesting indices across many dates at once, structure your integration to minimise round trips. Where possible, use query parameters (such as date ranges on the indices time-series endpoint) to retrieve multiple results in a single request rather than issuing individual requests in a loop.

If your use case requires bulk ingestion or batch processing at a scale not supported by the current API, contact support@example.com to discuss your requirements. Enterprise plans include dedicated support for high-volume integration patterns.

Overview

Endpoints

SemaiSens API Rate Limits, Quotas, and Backoff Strategies

Limits by Plan

Rate Limit Headers

Exceeding the Rate Limit

Best Practices

Exponential Backoff Example

Bulk Operations

​Limits by Plan

​Rate Limit Headers

​Exceeding the Rate Limit

​Best Practices

​Exponential Backoff Example

​Bulk Operations

Limits by Plan

Rate Limit Headers

Exceeding the Rate Limit

Best Practices

Exponential Backoff Example

Bulk Operations