Getting Started
Rate Limits & Errors

Rate Limits

The Jump EHR API enforces rate limits to ensure fair usage and maintain service reliability for all users.

Default Limits

Limit TypeDefaultWindow
Requests per hour1,000Resets on the hour

Rate limits are applied per API key. Each key has its own quota that resets at the top of every hour (e.g. 14:00, 15:00).

Need higher limits? Contact us to discuss increased quotas for your organisation.

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed per hour
X-RateLimit-RemainingRequests remaining in current window

Example Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-Request-Id: req_abc123

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 status with a RATE_LIMITED error code:

{
  "data": null,
  "meta": { "request_id": "req_abc123" },
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Limit: 1000 requests per hour. Resets on the hour."
  }
}

Best Practices

1. Monitor Your Usage

Check the X-RateLimit-Remaining header in responses to track your current usage:

const response = await fetch(
  'https://app.usejump.co.uk/functions/v1/api-v1/patients',
  { headers: { 'Authorization': 'Bearer pk_live_your_api_key' } }
);
 
const remaining = response.headers.get('X-RateLimit-Remaining');
console.log(`${remaining} requests remaining`);

2. Implement Exponential Backoff

When rate limited, wait before retrying with increasing delays:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
 
    return response;
  }
  throw new Error('Max retries exceeded');
}

3. Cache Responses

Reduce API calls by caching responses when appropriate:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute
 
async function getCachedPatient(patientId) {
  const cacheKey = `patient:${patientId}`;
  const cached = cache.get(cacheKey);
 
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
 
  const response = await fetch(
    `https://app.usejump.co.uk/functions/v1/api-v1/patients/${patientId}`,
    { headers: { 'Authorization': 'Bearer pk_live_your_api_key' } }
  );
 
  const { data } = await response.json();
  cache.set(cacheKey, { data, timestamp: Date.now() });
  return data;
}

4. Use Pagination Efficiently

When fetching multiple records, use list endpoints with pagination instead of individual requests:

# Better: One request for multiple patients
curl "https://app.usejump.co.uk/functions/v1/api-v1/patients?limit=100"
 
# Worse: Multiple requests for individual patients
# curl .../patients/id1
# curl .../patients/id2

Request Logging

All API requests are logged with the following information:

  • Endpoint and HTTP method
  • Response status code
  • Response time
  • Timestamp

You can view your API usage in the Jump EHR dashboard under Settings > API Keys > Usage.

Next Steps

AuthenticationOverview