Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tamradar.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

StatusDescriptionCommon Causes
400Bad RequestMissing required fields, invalid format
402Payment RequiredInsufficient balance
401UnauthorizedMissing or invalid API key
403ForbiddenValid API key but insufficient permissions
404Not FoundInvalid radar ID or resource not found
409ConflictDuplicate radar (includes existing radar ID for direct access)
429Rate Limit ExceededPer-minute budget exhausted or per-second burst limit exceeded
500Internal Server ErrorApplication bugs, unexpected code issues
503Service UnavailableDatabase 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"
}

​
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: 
{
  "field": "domain", 
  "reason": "A radar for this person at this company already exists. Conflicting radar_id: 2f5fb18f-f9cf-4411-bbef-10f5ef73324f. You can view it using GET /v1/radars/{radar_id}"
}
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:

Extract the radar_id from the reason message and fetch the existing radar: 
# Extract radar_id from 409 response reason field  
# Then fetch the existing radar directly
curl -X GET "https://api.tamradar.com/v1/radars/7e3dda58-a046-4746-8247-258b6fd9c3ac" \
  -H "x-api-key: your-api-key"

​
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

  1. Handle Consistent Structure: Parse the errors array for all non-2xx responses.
  2. Log Error IDs: Store error_id for support requests and debugging.
  3. Handle Rate Limits: Implement exponential backoff when rate limited
  4. Validate Input: Pre-validate requests to minimize validation errors
  5. 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:
  1. Note the error_id
  2. Check our status page
  3. Contact support at support@tamradar.com
Include the following in support requests:
  • Error ID
  • Timestamp
  • Request details (endpoint, method)
  • Steps to reproduce