Error Handling - TAMradar API Docs

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"
}

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

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

​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)

​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