API Documentation is in beta. Report issues to developers@jump.health
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 hour100Rolling 1-hour window

Rate limits are applied per API key. Each key has its own quota that resets on a rolling basis.

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

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: 100
X-RateLimit-Remaining: 87
X-Response-Time: 45ms
X-Request-Id: req_abc123

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests status code:

{
  "error": "Rate limit exceeded",
  "details": "You have exceeded the maximum number of requests. Please try again later.",
  "request_id": "req_abc123"
}

Response Headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

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',
      'Content-Type': 'application/json'
    }
  }
);
 
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 Webhooks for Real-Time Updates

Instead of polling the API, use webhooks to receive notifications when data changes:

  • Subscribe to events like patient.updated or appointment.created
  • Receive real-time updates without consuming your rate limit
  • More efficient for applications that need current data

5. Batch Operations

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
# curl .../patients/id3

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