Troubleshooting

Rate limiting

The API implements multiple layers of rate limiting to ensure fair usage and service stability:

1. Request Rate Limits

All requests are subject to per-second rate limits to protect against traffic spikes. These limits vary based on endpoint type and authentication status. If you consistently hit these limits, consider implementing request batching or caching strategies.

2. Daily App Limits

Each partner application has a daily request quota with two thresholds:

• Soft Limit - When reached, requests continue but response headers will indicate the limit has been exceeded. You can view your app's soft limit in the Developer Portal under your app settings.
• Hard Limit - When reached, requests are blocked with HTTP 429 responses. You can view your app's hard limit in the Developer Portal under your app settings.

Notifications:

• At 90% of soft limit: Warning notification sent
• At soft limit: Notification sent, but requests continue
• At hard limit: Requests blocked until daily reset (midnight UTC)

The daily limits reset at midnight UTC. If you need higher limits, contact your Epidemic Sound partner manager.

3. Per-User Limits

To ensure fair usage across end users, individual users are limited to 350 requests per week per app. This applies to authenticated user requests and resets weekly.

Rate Limiting Response Headers

When rate limits are encountered, the API returns the following headers:

Daily App Limits:

• X-RateLimit-Reached: Set to "true" when soft or hard limit is reached
• X-RateLimit-Reset: Timestamp when the limit resets (midnight UTC)

Per-User Limits:

• x-user-ratelimit-count: Current request count for the user
• x-user-ratelimit-limit: Maximum allowed requests (350)
• X-User-Rate-Limit-Reset: Time until the limit resets

HTTP 429 Response: When the hard limit is reached, the API responds with HTTP 429 (Too Many Requests). Implement exponential backoff and retry logic to handle this gracefully.

Best Practices

To stay within rate limits:

• Use batch requests where possible
• Monitor the rate limit headers in responses
• Set up alerts at 80-90% of your daily quota

If you encounter rate limit errors, contact us and include which endpoint you're calling and the error you're seeing. Using a single user token for all your users often triggers per-second (spike) limits — use unique user tokens per end user where possible.

Transient errors (HTTP 502, 503, 504)

These are transient errors caused by intermediate network components (load balancers, proxies, etc.) between your servers and ours. They are expected to occur occasionally and do not indicate a problem with your integration.

Implement an exponential backoff retry strategy so these do not surface as errors to your end users:

Attempt	Wait time
1st retry	5ms
2nd retry	10ms
3rd retry	20ms
4th retry	40ms
5th retry	80ms

If errors persist beyond 5 retries, log the incident and surface a user-friendly message.

Retries and DDoS protection

To ensure the stability of the API, we use web application firewall solutions that protect against malicious attacks. In many cases, this allows us to mitigate attacks without affecting users. However, it is sometimes hard to distinguish between an attack and an unintentional request overload from well-intended clients, sometimes referred to as friendly fire.

You can decrease the risk that your client gets mistaken for a malicious actor by implementing delays for any request retries, for example, by using the exponential backoff strategy described above.

DDoS mitigation responses

When the web application firewall denies requests in order to mitigate an ongoing DDoS attack, it may respond with 502 Bad Gateway and an empty response body. We do our best to ensure this does not affect requests from legitimate clients, but unfortunately, this can not always be avoided, and therefore we advise you to handle this case in your clients.