Rate Limits & Errors

Understand Jump EHR API rate limits, error codes, and best practices for handling API responses.

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

Default Limits

Limit Type	Default	Window
Requests per hour	1,000	Resets 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:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per hour
`X-RateLimit-Remaining`	Requests 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

Learn about Authentication and API keys
Explore the API Reference for endpoint details

On this page