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

# Common errors

# Common Errors & Solutions

Here are the most common errors you'll encounter with Posthoot and how to fix them.

## 🔐 Authentication Errors

### `401 Unauthorized`

**Problem**: Invalid or expired API key
**Solution**:

* Check your API key is correct
* Ensure the key hasn't expired
* Verify you're using the right environment (dev/prod)

```bash theme={"dark"}
# Check your API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.posthoot.com/api/v1/users/me
```

### `403 Forbidden`

**Problem**: Insufficient permissions
**Solution**:

* Verify your account has the required permissions
* Check if your subscription plan includes this feature
* Contact support if you believe this is an error

## ⚡ Rate Limiting Errors

### `429 Too Many Requests`

**Problem**: You've hit the rate limit
**Solution**:

* Check the `X-RateLimit-Remaining` header
* Wait for the reset time shown in `X-RateLimit-Reset`
* Implement exponential backoff in your code

```javascript theme={"dark"}
// Example: Handle rate limiting
const response = await fetch('/api/v1/email/send', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset');
  const waitTime = (resetTime * 1000) - Date.now();
  await new Promise(resolve => setTimeout(resolve, waitTime));
}
```

## 📧 Email Sending Errors

### `400 Bad Request - Invalid SMTP Configuration`

**Problem**: SMTP settings are incorrect
**Solution**:

* Verify SMTP host, port, username, password
* Check if your SMTP provider requires SSL/TLS
* Test SMTP connection separately

### `500 Internal Server Error - Email Delivery Failed`

**Problem**: Email couldn't be delivered
**Solution**:

* Check recipient email address is valid
* Verify your SMTP provider is working
* Review email content for spam triggers
* Check your sending reputation

## 📊 Analytics Errors

### `404 Not Found - Analytics Data Unavailable`

**Problem**: Requested analytics data doesn't exist
**Solution**:

* Ensure the campaign/email ID is correct
* Check if enough time has passed for data collection
* Verify the date range is valid

### `422 Unprocessable Entity - Invalid Date Range`

**Problem**: Date parameters are invalid
**Solution**:

* Use ISO 8601 format: `2024-01-01T00:00:00Z`
* Ensure start date is before end date
* Check date range isn't too large (max 90 days)

## 🔧 General API Errors

### `500 Internal Server Error`

**Problem**: Server-side error
**Solution**:

* Check our [status page](https://status.posthoot.com)
* Retry the request (implement retry logic)
* Contact support if persistent

### `502 Bad Gateway`

**Problem**: Service temporarily unavailable
**Solution**:

* Wait a few minutes and retry
* Check if maintenance is scheduled
* Monitor our status page for updates

## 🛠️ Debugging Tips

### Enable Debug Logging

```javascript theme={"dark"}
// Add debug headers to see what's happening
const response = await fetch('/api/v1/email/send', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Debug': 'true'
  }
});

console.log('Response headers:', response.headers);
console.log('Response body:', await response.json());
```

### Check Request Format

```bash theme={"dark"}
# Test your API call with curl
curl -X POST https://api.posthoot.com/api/v1/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Test Email",
    "body": "Hello World"
  }'
```

## 📞 Still Having Issues?

If none of these solutions work:

1. **Check our logs**: Enable debug mode to see detailed error messages
2. **Review recent changes**: Did you recently update your code or configuration?
3. **Contact support**: Include your request ID and error details

**Support Email**: [support@posthoot.com](mailto:support@posthoot.com)
**Community**: [Discord](https://discord.gg/MXQgb9s5bA)