> ## Documentation Index
> Fetch the complete documentation index at: https://trakkr.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Learn about error responses and status codes from the Trakkr API

The Trakkr API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with our servers.

## Error Response Format

All error responses follow this format:

```json theme={null}
{
  "error": "Error title",
  "errors": ["Detailed error message"]
}
```

## HTTP Status Codes

| Status Code | Description                                             |
| ----------- | ------------------------------------------------------- |
| `200`       | Success - The request was successful                    |
| `400`       | Bad Request - The request was invalid                   |
| `401`       | Unauthorized - Missing or invalid API key               |
| `403`       | Forbidden - Valid API key but insufficient permissions  |
| `500`       | Internal Server Error - Something went wrong on our end |

## Common Error Responses

### 400 Bad Request

#### Missing Required Parameter

```json theme={null}
{
  "error": "Missing required parameter: brand",
  "errors": ["brand parameter is required"]
}
```

#### Invalid Breakdown Format

```json theme={null}
{
  "error": "Invalid breakdown parameter format",
  "errors": ["breakdown must be a valid JSON array"]
}
```

#### Invalid Breakdown Values

```json theme={null}
{
  "error": "Invalid breakdown values",
  "errors": ["Invalid breakdown values: ['invalid']. Valid values are: ['model', 'prompt']"]
}
```

#### Invalid Date Format

```json theme={null}
{
  "error": "Invalid start_date format",
  "errors": ["start_date must be in YYYY-MM-DD format"]
}
```

#### Date Range Too Large

```json theme={null}
{
  "error": "Date range too large",
  "errors": ["The total date range cannot exceed 90 days"]
}
```

### 401 Unauthorized

#### Missing API Key

```json theme={null}
{
  "error": "Missing API key",
  "errors": ["API key must be provided in the Authorization header as 'Bearer <api_key>'"]
}
```

### 403 Forbidden

#### Invalid API Key

```json theme={null}
{
  "error": "Invalid API key",
  "errors": ["No accounts found for this API key"]
}
```

#### Brand Access Denied

```json theme={null}
{
  "error": "Brand access denied",
  "errors": ["You do not have access to this brand"]
}
```

### 500 Internal Server Error

#### Authentication Error

```json theme={null}
{
  "error": "Authentication error",
  "errors": ["Could not validate API key against database"]
}
```

#### Date Range Validation Error

```json theme={null}
{
  "error": "Date range validation error",
  "errors": ["Could not validate date range: invalid date format"]
}
```

#### General Server Error

```json theme={null}
{
  "error": "Internal server error",
  "errors": ["An unexpected error occurred: [error details]"]
}
```

## Handling Errors

### JavaScript Example

```javascript theme={null}
try {
  const response = await fetch('https://api.trakkr.ai/get-scores', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      brand: '0000000000000x000000000000000000',
      breakdown: ['model']
    })
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error(`Error ${response.status}:`, errorData.error);
    console.error('Details:', errorData.errors);
    return;
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Network error:', error);
}
```

### Python Example

```python theme={null}
import requests

try:
    response = requests.post(
        'https://api.trakkr.ai/get-scores',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'brand': '0000000000000x000000000000000000',
            'breakdown': ['model']
        }
    )
    
    if response.status_code != 200:
        error_data = response.json()
        print(f"Error {response.status_code}: {error_data.get('error')}")
        print(f"Details: {error_data.get('errors')}")
    else:
        data = response.json()
        print('Success:', data)
        
except requests.exceptions.RequestException as e:
    print(f"Network error: {e}")
```

## Error Handling Best Practices

1. **Check status codes**: Always check the HTTP status code before processing the response
2. **Parse error messages**: Extract both the error title and detailed messages
3. **Handle network errors**: Catch and handle network-level exceptions
4. **Log errors**: Log error details for debugging purposes
5. **Retry logic**: Consider implementing retry logic for 5xx errors
6. **User feedback**: Provide meaningful error messages to end users

## Rate Limiting

While the API doesn't have strict rate limits, we recommend:

* Making reasonable numbers of requests
* Implementing exponential backoff for retries
* Caching responses when appropriate
* Avoiding rapid-fire requests

<Note>
  **Need help debugging?** If you're getting unexpected errors, check our [authentication guide](/authentication) or [contact support](mailto:mack@trakkr.ai) with the full error response.
</Note>