Error Handling

Overview

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

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

Error Response Format

JSON

{
  "status": "error",
  "code": 400,
  "message": "Validation failed",
  "data": [
    {
      "field": "domain",
      "reason": "Domain is required"
    }
  ],
  "error_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "timestamp": "2024-01-01T12:00:00Z"
}

Error Types

Status	Error Type	Description	Common Causes
400	validation_error	Request validation failed	Missing fields, invalid format
401	authentication_error	Authentication failed	Missing or invalid API key
402	insufficient_credits	Insufficient credits	Not enough credits for operation
403	authorization_error	Permission denied	Insufficient access rights
404	not_found_error	Resource not found	Invalid radar ID
409	duplicate_error	Resource conflict	Duplicate radar configuration
429	rate_limit_error	Rate limit exceeded	Too many requests
500	server_error	Internal server error	Unexpected server issues

Common Error Examples

Validation Error (400)

JSON

{
  "status": "error",
  "code": 400,
  "message": "Validation failed",
  "data": [
    {
      "field": "radar_type",
      "reason": "Invalid radar type provided"
    },
    {
      "field": "webhook_url",
      "reason": "Webhook URL must be a valid HTTPS URL"
    }
  ],
  "error_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "timestamp": "2024-01-01T12:00:00Z"
}

Insufficient Credits Error (402)

JSON

{
  "status": "error",
  "code": 402,
  "message": "Insufficient credits",
  "data": [
    {
      "field": "credits",
      "reason": "Your account has insufficient credits. Required: 5, Available: 2",
      "details": {
        "required_credits": 5,
        "available_credits": 2,
        "next_expiry": "2024-05-01T00:00:00Z"
      }
    }
  ],
  "error_id": "e290f1ee-6c54-4b01-90e6-d701748f0853",
  "timestamp": "2024-01-01T12:00:00Z"
}

Already Deactivated Error (400)

JSON

{
  "status": "error",
  "code": 400,
  "message": "Radar already deactivated",
  "data": [
    {
      "field": "radar_status",
      "reason": "Radar is already in deactivated state",
      "details": {
        "deactivation_date": "2024-01-01T00:00:00Z",
        "grace_period_end": "2024-02-01T00:00:00Z"
      }
    }
  ],
  "error_id": "f290f1ee-6c54-4b01-90e6-d701748f0854",
  "timestamp": "2024-01-01T12:00:00Z"
}

Rate Limiting

Rate limits are enforced per API key:

• Standard tier: 60 requests per minute
• Enterprise tier: 1000+ requests per minute

When rate limited, you'll receive:

JSON

{
  "status": "error",
  "code": 429,
  "message": "Rate limit exceeded",
  "data": [
    {
      "field": "rate_limit",
      "reason": "Too many requests",
      "details": {
        "limit": 60,
        "remaining": 0,
        "reset_at": "2024-01-01T12:01:00Z"
      }
    }
  ],
  "error_id": "g290f1ee-6c54-4b01-90e6-d701748f0855",
  "timestamp": "2024-01-01T12:00:00Z"
}

Best Practices

1. Check Error Types: Always check the error_type field to handle specific errors
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. Monitor Credits: Check credit balance regularly to avoid insufficient credit errors

Error Recovery

For transient errors (500, 503):

• 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
• Resubmit with corrected data

For credit errors (402):

• Check current credit balance
• Purchase additional credits if 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