Authentication & Rate Limits

API Key Authentication

All requests to TAMradar API must include your API key. This key uniquely identifies your account and authorizes access to our services.

Using Your API Key

Include your API key in the x-api-key header with every request:

Bash

# Example GET request
curl "https://api.tamradar.com/v1/radars" \
     -H "x-api-key: YOUR_API_KEY"

# Example POST request
curl -X POST "https://api.tamradar.com/v1/radars" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "example.com",
       "radar_type": "job_openings"
     }'

Authentication Errors

If authentication fails, you'll receive a 401 response:

JSON

{
  "status": "error",
  "code": 401,
  "message": "Invalid or inactive API key",
  "errors": [{ "field": "x-api-key", "reason": "Invalid or inactive API key" }],
  "timestamp": "2024-01-01T12:00:00Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Rate Limits

Standard Limits

Bucket	Default
Write (create radars)	100 per minute, 10 per second
Read (GET radars, updates)	200 per minute, 10 per second

Higher limits are available on enterprise plans — contact [email protected].

How limits are counted

There are two separate budgets — write and read — so a heavy polling client doesn't eat into your creation budget.

Method	Endpoints	Budget used
POST	/v1/radars, /v1/radars/bulk	Write (100/min, 10/sec)
GET	/v1/radars, /v1/radars/:id, /v1/updates, /v1/account	Read (200/min, 10/sec)
DELETE	/v1/radars/:id	Read (200/min, 10/sec)

Single creates (POST /v1/radars) deduct 1 token from your per-minute write budget and 1 from your per-second burst budget.

Bulk requests (POST /v1/radars/bulk) deduct N tokens from your per-minute write budget (where N = number of radars in the request), and 1 token from your per-second burst budget regardless of size. A bulk of 50 costs the same as 50 individual creates.

Bulk requests are all-or-nothing

Rate limit is checked before any radars are created. If your remaining budget is less than the bulk size, the entire request is rejected — no radars are created, nothing is billed.

Example — 100/min limit:

  t=0s:  POST /v1/radars/bulk  (80 items) → OK, 20 tokens remaining
  t=3s:  POST /v1/radars/bulk  (30 items) → 429: only ~21 tokens available
         Retry-After: 51        ← wait this many seconds, then retry the full 30
         X-RateLimit-Remaining: 21  ← or send 21 right now

Contrast with balance: Insufficient balance is discovered per-item mid-creation (returns 207 with some 402s). Rate limit is a gateway — either the whole bulk proceeds or nothing does.

Response headers

Successful single-endpoint requests (create, get, delete) include these headers so you can track your remaining budget. Bulk requests (/v1/radars/bulk) only include these headers on 429 — not on 201/207 success.

Header	Meaning
X-RateLimit-Limit	Your per-minute budget for this endpoint
X-RateLimit-Remaining	Tokens remaining after this request
X-RateLimit-Reset	Seconds until the bucket fully refills

Handling Rate Limits

When you exceed the rate limit you'll receive a 429 with three headers:

Header	Meaning
Retry-After	Seconds until you have enough budget to retry
X-RateLimit-Limit	Your per-minute budget
X-RateLimit-Remaining	Tokens available right now

The reason field tells you which bucket fired:

• minute — per-minute budget exhausted, wait Retry-After seconds
• burst — per-second burst limit hit, retry in 1 second

JSON

{
  "status": "error",
  "code": 429,
  "message": "Per-minute rate limit exceeded. Retry after 51 seconds.",
  "errors": [{ "field": "rate_limit", "reason": "minute" }],
  "timestamp": "2024-01-01T12:00:00Z"
}

Rate limit vs. bulk size pre-check

If your bulk is larger than your entire per-minute budget (impossible to ever succeed), you get a 400 instead of 429:

JSON

{
  "status": "error",
  "code": 400,
  "message": "Bulk of 150 exceeds your per-minute radar budget of 100. Split into smaller requests or contact support to raise your limit.",
  "errors": [{ "field": "radars", "reason": "bulk_exceeds_rate_limit" }]
}

400 = permanent problem (split your bulk). 429 = transient problem (wait and retry).

Enterprise Options

For higher volume needs, we offer customized plans with:

• Increased rate limits
• Priority support

Contact [email protected] to discuss your requirements.

Need Help?

• Check our Error Handling guide
• Contact [email protected]