Error Handling

Overview

The TAMradar API uses standard HTTP status codes and a consistent error response format. Error responses have different structures based on the error type:

Standard Error Response (400, 403, 404, 409, 429, 500)

status: Always "error" for error responses
code: HTTP status code
message: Human-readable error description
data: Array of field-level errors (null for 500 errors)
timestamp: When the error occurred
error_id: Unique identifier for error tracking

Authentication Error Response (401)

status: Always "error" for error responses
code: 401
message: Human-readable error description
details: Array of field-level errors (not data)
timestamp: When the error occurred

Error Response Formats

Standard Error Format (400, 403, 404, 409, 429)

{
  "status": "error",
  "code": 400,
  "message": "Invalid request body",
  "data": [
    {
      "field": "domain",
      "reason": "Invalid domain format"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Authentication Error Format (401)

{
  "status": "error",
  "code": 401,
  "message": "Missing API key",
  "details": [
    {
      "field": "x-api-key",
      "reason": "API key is required"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z"
}

Server Error Format (500)

{
  "status": "error",
  "code": 500,
  "message": "An internal server error occurred.",
  "data": null,
  "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, 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	Too many requests
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",
  "data": [
    {
      "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 (400)

{
  "status": "error",
  "code": 400,
  "message": "Insufficient balance",
  "data": [
    {
      "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",
  "details": [
    {
      "field": "x-api-key",
      "reason": "API key is required"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z"
}

Permission Error (403)

{
  "status": "error",
  "code": 403,
  "message": "Insufficient permissions",
  "data": [
    {
      "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 /radars/{radar_id}.

{
  "status": "error",
  "code": 409,
  "message": "Conflict: Radar already exists",
  "data": [
    {
      "field": "domain",
      "reason": "A radar with this domain and type already exists for your account. Conflicting radar_id: abc123-def456-7890-1234-567890abcdef. You can view it using GET /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: abc123... You can view it using GET /radars/{radar_id}"
}

Contact Radars:

{
  "field": "domain", 
  "reason": "A radar for this person at this company already exists. Conflicting radar_id: def456... You can view it using GET /radars/{radar_id}"
}

Industry Radars:

{
  "field": "keyword",
  "reason": "An industry mentions radar for this configuration (keyword \"artificial intelligence\") already exists. Conflicting radar_id: ghi789... You can view it using GET /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://radar-api.tamradar.com/v1/radars/abc123-def456-7890-1234-567890abcdef" \
  -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": "Rate limit exceeded",
  "data": [
    {
      "field": "rate_limit",
      "reason": "Too many requests"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}

Server Error (500)

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

Service Unavailable (503)

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

Best Practices

Handle Different Response Structures: Note that 401 errors use details field while others use data
Log Error IDs: Store error_id for support requests and debugging (not present in 401 responses)
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 [email protected]

Include the following in support requests:

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