Error Codes

Error Response Format

All errors return a JSON response:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

400 Bad Request

Invalid request format or missing required fields.

{
  "error": "Invalid payload: 'title' is required",
  "code": "INVALID_PAYLOAD"
}

Common causes:

• Missing required fields in payload
• Invalid JSON syntax
• Invalid field values (e.g., unknown severity)

Fix: Check your payload against the Webhook Formats documentation.

401 Unauthorized

Authentication failed.

{
  "error": "Invalid integration ID",
  "code": "UNAUTHORIZED"
}

Common causes:

• Typo in webhook URL
• Integration was deleted
• URL was regenerated (old URL no longer valid)

Fix: Copy the current webhook URL from Settings > Integrations.

404 Not Found

Integration not found.

{
  "error": "Integration not found",
  "code": "NOT_FOUND"
}

Common causes:

• Wrong URL path (e.g., /grafana/ vs /generic/)
• Integration ID doesn't exist

Fix: Verify the full webhook URL in your integration settings.

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 60
}

Common causes:

• Too many alerts in short period
• Alert storm from monitoring tool
• Misconfigured alerting rules

Fix:

• Wait for the retryAfter period
• Review your alerting rules for excessive firing
• Consider alert aggregation at the source

500 Internal Server Error

Server-side error processing the request.

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Common causes:

• Temporary service issues
• Database connectivity problems

Fix: Retry the request. If persistent, contact [email protected].

Troubleshooting

Alert Not Appearing

1. Check response code - Did you get 202?
2. Check integration - Is it showing activity?
3. Check policies - Is there a matching policy?
4. Check suppression - Is a suppression window active?

Webhook Timing Out

1. Check URL - Is the full URL correct?
2. Check network - Can your server reach irm.nearlunar.com?
3. Check firewall - Are outbound HTTPS connections allowed?

Duplicate Alerts

1. Check incident key - Are you sending unique keys?
2. Check labels - Different labels = different alert
3. Review deduplication - See Webhook Formats

Getting Help

If you're stuck:

1. Check this documentation
2. Review your integration's activity log
3. Email [email protected] with:
   • Integration ID (not the full URL)
   • Timestamp of the failed request
   • Error response you received