3. Rate Limiting

While communicating with MetaDefender Cloud APIs, you will need to use the authentication mechanism for the given API endpoint and provide your apikey. Each apikey has daily limits, and you can check yours by logging in to MetaDefender Cloud with your OPSWAT account. Additionally, the MetaDefender Cloud server returns custom headers in each response that will help you track your current API usage.

If you don't have an apikey, see our guide: Onboarding Process for MetaDefender Cloud API Users

Each MetaDefender Cloud apikey has limits for each family of APIs (Prevention, Reputation, etc), and every response from MetaDefender Cloud contains custom headers that inform clients about the current limit.

Description of Custom Headers

  • X-RateLimit-Limit - Your current limit for a given family of APIs.

  • X-RateLimit-Remaining - The number of requests remaining in the current time window, usually set to 24 hours.

  • X-RateLimit-Reset-In - The number of seconds remaining in the current time window.

  • X-RateLimit-Used - The number of requests used in the current time window.

Custom Header Example

> curl -vvvv "https://api.metadefender.com/v4/hash/64638C3FF08EECD62E2B24708CF5B5F111C05E3D" -H 'apikey: YOUR_API_KEY'
> GET /v4/hash/64638C3FF08EECD62E2B24708CF5B5F111C05E3D HTTP/1.1
> Host: api.metadefender.com
> User-Agent: curl/7.52.1
> Accept: */*
> apikey: YOUR_API_KEY
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
< HTTP/2 200
< date: Mon, 11 May 2020 09:41:18 GMT
< content-type: application/json; charset=utf-8
< content-length: 5280
< vary: Accept-Encoding, Origin
< x-authenticated: by apikey
< x-account-type: other
< x-ratelimit-for: reputation_api
< x-ratelimit-limit: 4000
< x-ratelimit-used: 1
< x-ratelimit-remaining: 3999
< x-ratelimit-reset-in: 86400s
< x-ratelimit-interval: 86400
< x-redis-partial-cache: true
< x-content-type-options: nosniff
< etag: "14a0-xGmnaISdKYosJha3G+h2JjEfaQg"
< x-response-time: 330ms

When doing a bulk request, the limit is subtracted for every successful response.

E.g.: doing a bulk hash lookup for 20 hashes, where only the last 15 are found in our database, and the remaining limit is 10 lookups, the response will contain the first 5 hashes marked as found, and the next 10 hashes results. We do not count the not found ones for the limit, but we do count when looking up duplicates in different requests. In the same request, we do not count the duplicates.

Exceeding allowed rate limit

When the rate limit is exceeded (user performing more requests per day that the license limit) an HTTP 429 code is returned with the following body:

"error": {
"code": 429000,
"messages": [
"Rate limit exceeded, retry after the limit is reset. Limit: 100 requests / day"

The limit is reset after 24 hours from the first request. E.g: if an apikey starts calling the API at 11:00 AM and finishes up the rate limit by 22:00 PM, the rate limit will be reset the next day at 11:00 AM.