> ## 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.

# Error Handling

> Standard error envelope, common failure scenarios, and recovery patterns.

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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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}`.

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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](https://status.tamradar.com)
3. Contact support at [support@tamradar.com](mailto:support@tamradar.com)

Include the following in support requests:

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