Usage Limits

How many requests your plan includes, how the per-second flood limit works and which calls are free.

Plan quota#

Each plan includes a number of requests per billing cycle. Every successful or failed call to a billable method made with a live key counts as one request.

Plans and their quotas can change; the dashboard (https://gurdx.cretip.com/app) always shows the current figures and your live consumption.

When you pass the quota, the API returns error 103 limit_reached. Upgrade the plan or settle unpaid invoices to continue.

Note: Usage is read from a counter that refreshes about once a minute, so the call that crosses the limit may be followed by a few more successful ones before error 103 starts.

Flood limit#

Independently of your quota, each account may send at most 1,000 requests per second. Above that, the API returns error 106 flood_detected. The counter resets every second, so a short pause is enough.

async function call(url, tries = 3) {
  const res = await fetch(url).then((r) => r.json());
  if (res.status === "error" && res.code === 106 && tries > 0) {
    await new Promise((r) => setTimeout(r, 300));
    return call(url, tries - 1);
  }
  return res;
}

Bulk requests#

Bulk IP Lookup accepts several addresses in one HTTP call, which reduces round trips and helps you stay under the flood limit. The call is metered as one request.

What does not count#

• Calls made in test mode (mode=test or a gx_test_ key). They are free and never raise events.
• User Data Deletion, which is not billable.
• Requests that fail before the key is proven, such as error 101, because they cannot be attributed to an account.

Plan access#

A plan can restrict which methods and modules you may use:

• Calling a method outside your plan returns error 117 feature_not_available.
• Asking for params=security without the security module returns error 114 security_module_not_allowed. See VPN and proxy detection.

Subscription state#

Keeping usage under control#

• Cache results that change slowly, such as country or BIN data.
• Use bulk lookups when you have many IPs.
• Develop with a gx_test_ key so tests do not consume quota.
• Watch the usage chart in the dashboard and alert before you reach the limit.