Rate Limits

The Uniship API enforces rate limits to ensure service stability and fair usage across all users.

General API Rate Limits

By default, each API key is limited to:

• 100 requests per minute for general API operations
• 1000 requests per hour per API key
• 10,000 requests per day per API key

Endpoint-Specific Limits

Some endpoints have specialized rate limits:

Endpoint Category	Limit	Time Period
Authentication	10	per minute
Shipping Channel creation	60	per hour
Tracking Parcel creation	300	per hour
Tracking status checks	1000	per hour
Webhook management	100	per hour

Rate Limit Headers

API responses include headers that provide information about your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1712780400

• X-RateLimit-Limit: Maximum number of requests allowed per time window
• X-RateLimit-Remaining: Number of requests remaining in the current window
• X-RateLimit-Reset: Unix timestamp when the rate limit window resets

Handling Rate Limit Errors

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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 47 seconds.",
    "retry_after": 47
  }
}

The retry_after field indicates the number of seconds to wait before making another request.

Best Practices

To avoid hitting rate limits:

1. Cache responses: Cache frequently accessed data that doesn't change often
2. Implement exponential backoff: When encountering rate limit errors, use exponential backoff with jitter
3. Batch requests: Use batch endpoints where available to reduce the number of API calls
4. Monitor usage: Track your API usage against the limits to avoid disruptions
5. Distribute traffic: Spread non-urgent requests evenly throughout the day

Exponential Backoff Example

When encountering rate limit errors, implement exponential backoff:

function makeRequestWithBackoff(url, retries = 3, backoff = 300) {
  return fetch(url)
    .then(response => {
      if (response.status === 429 && retries > 0) {
        const retryAfter = response.headers.get('Retry-After') || backoff;
        const jitter = Math.random() * 0.3 * backoff;
        const backoffTime = parseInt(retryAfter, 10) * 1000 + jitter;
        
        console.log(`Rate limited. Retrying in ${backoffTime/1000} seconds...`);
        
        return new Promise(resolve => {
          setTimeout(() => {
            resolve(makeRequestWithBackoff(url, retries - 1, backoff * 2));
          }, backoffTime);
        });
      }
      return response;
    })
    .catch(error => {
      if (retries > 0) {
        const jitter = Math.random() * 0.3 * backoff;
        const backoffTime = backoff + jitter;
        
        console.log(`Request failed. Retrying in ${backoffTime/1000} seconds...`);
        
        return new Promise(resolve => {
          setTimeout(() => {
            resolve(makeRequestWithBackoff(url, retries - 1, backoff * 2));
          }, backoffTime);
        });
      }
      throw error;
    });
}

Request Increase

If your use case requires higher rate limits, please contact the support team. Include:

1. Your account information
2. Description of your use case
3. Expected request volume
4. Specific endpoints you need increased limits for