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)

JSON

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

Authentication Error Format (401)

JSON

{
  "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)

JSON

{
  "status": "error",
  "code": 500,
  "message": "An internal server error occurred.",
  "data": null,
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "req_1234567890abcdef"
}

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, resource already exists
429	Rate Limit Exceeded	Too many requests
500	Internal Server Error	Unexpected server issues

Common Error Examples

Validation Error (400)

JSON

{
  "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": "req_1234567890abcdef"
}

Insufficient Balance Error (400)

JSON

{
  "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": "req_1234567890abcdef"
}

Authentication Error (401)

JSON

{
  "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)

JSON

{
  "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": "req_1234567890abcdef"
}

Duplicate Resource Error (409)

JSON

{
  "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."
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "req_1234567890abcdef"
}

Rate Limiting

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

JSON

{
  "status": "error",
  "code": 429,
  "message": "Rate limit exceeded",
  "data": [
    {
      "field": "rate_limit",
      "reason": "Too many requests"
    }
  ],
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "req_1234567890abcdef"
}

Server Error (500)

JSON

{
  "status": "error",
  "code": 500,
  "message": "An internal server error occurred.",
  "data": null,
  "timestamp": "2024-03-20T10:15:30Z",
  "error_id": "req_1234567890abcdef"
}

Best Practices

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

Include the following in support requests:

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