Error Handling

Overview

The TAMradar API uses standard HTTP status codes and a consistent error response format.

Error Response Envelope (400, 401, 403, 404, 409, 429, 500, 503)

status: Always “error” for error responses
code: HTTP status code
message: Human-readable error description
errors: Array of field-level errors (field + reason). May be empty ([]) for some server-side failures.
timestamp: When the error occurred
error_id: Unique identifier for error tracking

Error Response Formats

Error Format Example (400)

{
  "status": "error",
  "code": 400,
  "message": "Invalid parameters",
  "errors": [
    {
      "field": "id",
      "reason": "Must be a valid UUID"
    }
  ],
  "timestamp": "2026-05-24T19:04:43Z",
  "error_id": "a559c1de-216b-46e6-977c-f9ceda7d79f7"
}

Server Error Format (500)

{
  "status": "error",
  "code": 500,
  "message": "An internal server error occurred.",
  "errors": [],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Error Types

Status	Description	Common Causes
400	Bad Request	Missing required fields, invalid format
402	Payment Required	Insufficient balance
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Invalid radar ID or resource not found
409	Conflict	Duplicate radar (includes existing radar ID for direct access)
429	Rate Limit Exceeded	Per-minute budget exhausted or per-second burst limit exceeded
500	Internal Server Error	Application bugs, unexpected code issues
503	Service Unavailable	Database outages, external service downtime

Common Error Examples

Validation Error (400)

{
  "status": "error",
  "code": 400,
  "message": "Invalid request body",
  "errors": [
    {
      "field": "domain",
      "reason": "Invalid domain format. Please provide a valid domain (e.g., example.com)"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

`updates_since` Validation Errors (400)

updates_since must be an RFC 3339 timestamp with an explicit timezone. It must represent now or a past instant and cannot be more than five calendar years old. The API allows up to five seconds of clock skew, but this is not future scheduling. Timezone missing:

{
  "status": "error",
  "code": 400,
  "message": "Invalid updates_since",
  "errors": [
    {
      "field": "updates_since",
      "reason": "must be an RFC 3339 timestamp with explicit timezone (e.g. 2026-01-01T00:00:00Z or +05:30 offset)"
    }
  ],
  "timestamp": "2026-08-12T10:00:00Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Future timestamp beyond clock-skew tolerance:

{
  "status": "error",
  "code": 400,
  "message": "Invalid updates_since",
  "errors": [
    {
      "field": "updates_since",
      "reason": "must not be more than 5 seconds in the future"
    }
  ],
  "timestamp": "2026-08-12T10:00:00Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Older than the five-calendar-year limit:

{
  "status": "error",
  "code": 400,
  "message": "Invalid updates_since",
  "errors": [
    {
      "field": "updates_since",
      "reason": "is too far in the past. Earliest accepted: 2021-08-12T10:00:00.000Z"
    }
  ],
  "timestamp": "2026-08-12T10:00:00Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Insufficient Balance Error (402)

{
  "status": "error",
  "code": 402,
  "message": "Insufficient balance",
  "errors": [
    {
      "field": "balance",
      "reason": "You do not have enough balance to create this radar."
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Authentication Error (401)

{
  "status": "error",
  "code": 401,
  "message": "Missing API key",
  "errors": [
    {
      "field": "x-api-key",
      "reason": "API key is required"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Permission Error (403)

{
  "status": "error",
  "code": 403,
  "message": "Insufficient permissions",
  "errors": [
    {
      "field": "permission",
      "reason": "Your API key does not have permission to create radars"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Duplicate Resource Error (409)

When creating a radar that already exists, the API returns the existing radar’s ID so you can fetch it directly using GET /v1/radars/{radar_id}.

{
  "status": "error",
  "code": 409,
  "message": "Conflict: Radar already exists",
  "errors": [
    {
      "field": "domain",
      "reason": "A radar with this domain and type already exists for your account. Conflicting radar_id: 7e3dda58-a046-4746-8247-258b6fd9c3ac. You can view it using GET /v1/radars/{radar_id}"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Different Radar Types Have Specific Error Messages:

Company Radars:

{
  "field": "domain",
  "reason": "A radar with this domain and type already exists for your account. Conflicting radar_id: 7e3dda58-a046-4746-8247-258b6fd9c3ac. You can view it using GET /v1/radars/{radar_id}"
}

Contact Radars: The field identifies which hard identifier matched the existing radar. Email match:

{
  "field": "identifiers.email",
  "reason": "A radar for this person at this company already exists. Each person can only be tracked once per domain. Conflicting radar_id: 2f5fb18f-f9cf-4411-bbef-10f5ef73324f. You can view it using GET /radars/{radar_id}",
  "conflicting_radar_id": "2f5fb18f-f9cf-4411-bbef-10f5ef73324f"
}

Profile URL match:

{
  "field": "identifiers.profile_url",
  "reason": "A radar for this person at this company already exists. Each person can only be tracked once per domain. Conflicting radar_id: 2f5fb18f-f9cf-4411-bbef-10f5ef73324f. You can view it using GET /radars/{radar_id}",
  "conflicting_radar_id": "2f5fb18f-f9cf-4411-bbef-10f5ef73324f"
}

Industry Radars:

{
  "field": "keyword",
  "reason": "An industry mentions radar for this configuration (keyword \"artificial intelligence\") already exists. Conflicting radar_id: 7e3dda58-a046-4746-8247-258b6fd9c3ac. You can view it using GET /v1/radars/{radar_id}"
}

Using the Returned Radar ID:

Read errors[0].conflicting_radar_id and fetch the existing radar:

# Read conflicting_radar_id from the 409 response, then fetch that radar
curl -X GET "https://api.tamradar.com/v1/radars/7e3dda58-a046-4746-8247-258b6fd9c3ac" \
  -H "x-api-key: your-api-key"

Platform accounts: duplicate creation can be enabled. For platform use cases (e.g. managing radars on behalf of your own customers), duplicate radar creation can be enabled account-wide on request — contact support. When enabled:

Creating the same radar definition again returns 201 with a new, independent radar_id instead of 409 — every successful create is a new radar.
TAMradar does not deduplicate create requests for your account. You own retry idempotency: store each returned radar_id, and don’t blind-retry timeouts — a request that timed out may still have succeeded and created a radar.
Each radar bills independently, including duplicates.
This applies to single and bulk creation alike.

Rate Limiting

Rate limits are enforced per API key. When rate limited, you’ll receive:

{
  "status": "error",
  "code": 429,
  "message": "Per-minute rate limit exceeded. Retry after 51 seconds.",
  "errors": [
    {
      "field": "rate_limit",
      "reason": "minute"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

For POST /v1/radars/bulk, the 429 message is Rate limit exceeded — wait and retry. with reason: "minute".

Server Error (500)

{
  "status": "error",
  "code": 500,
  "message": "An internal server error occurred.",
  "errors": [],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Service Unavailable (503)

{
  "status": "error",
  "code": 503,
  "message": "Service temporarily unavailable",
  "errors": [],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Best Practices

Handle Consistent Structure: Parse the errors array for all non-2xx responses.
Log Error IDs: Store error_id for support requests and debugging.
Handle Rate Limits: Implement exponential backoff when rate limited
Validate Input: Pre-validate requests to minimize validation errors
Check Balance: Monitor account balance to avoid insufficient balance errors

Error Recovery

For server errors (500):

Implement retry logic with exponential backoff
Maximum 3 retry attempts recommended
Add jitter to prevent thundering herd

For service unavailable (503):

Implement retry logic with exponential backoff
Maximum 5 retry attempts recommended (infrastructure usually recovers)
Start with longer delays (30s, 60s, 120s…)
Check our status page for ongoing incidents

For validation errors (400):

Log the specific validation failures
Fix the request payload based on the reason field
Resubmit with corrected data

For authentication errors (401):

Verify API key is correctly formatted
Check API key is included in x-api-key header
Ensure API key is active and valid

For insufficient balance errors (400):

Check current balance via account dashboard
Top up balance as needed
Retry the operation

Support

If you need help resolving errors:

Note the error_id
Check our status page
Contact support at support@tamradar.com

Include the following in support requests:

Error ID
Timestamp
Request details (endpoint, method)
Steps to reproduce

Introduction / Overview

Getting Started

Core Guides

Agentic Setup

API Reference

Bulk

Webhooks

Overview

Error Response Envelope (400, 401, 403, 404, 409, 429, 500, 503)

Error Response Formats

Error Format Example (400)

Server Error Format (500)

Error Types

Common Error Examples

Validation Error (400)

`updates_since` Validation Errors (400)

Insufficient Balance Error (402)

Authentication Error (401)

Permission Error (403)

Duplicate Resource Error (409)

Different Radar Types Have Specific Error Messages:

Using the Returned Radar ID:

Rate Limiting

Server Error (500)

Service Unavailable (503)

Best Practices

Error Recovery

Support

​Overview

​Error Response Envelope (400, 401, 403, 404, 409, 429, 500, 503)

​Error Response Formats

​Error Format Example (400)

​Server Error Format (500)

​Error Types

​Common Error Examples

​Validation Error (400)

​updates_since Validation Errors (400)

​Insufficient Balance Error (402)

​Authentication Error (401)

​Permission Error (403)

​Duplicate Resource Error (409)

​Different Radar Types Have Specific Error Messages:

​Using the Returned Radar ID:

​Rate Limiting

​Server Error (500)

​Service Unavailable (503)

​Best Practices

​Error Recovery

​Support

Overview

Error Response Envelope (400, 401, 403, 404, 409, 429, 500, 503)

Error Response Formats

Error Format Example (400)

Server Error Format (500)

Error Types

Common Error Examples

Validation Error (400)

`updates_since` Validation Errors (400)

Insufficient Balance Error (402)

Authentication Error (401)

Permission Error (403)

Duplicate Resource Error (409)

Different Radar Types Have Specific Error Messages:

Using the Returned Radar ID:

Rate Limiting

Server Error (500)

Service Unavailable (503)

Best Practices

Error Recovery

Support