AI Error Explanations

FirmHook's AI Error Explainer turns cryptic HTTP failures into plain-English diagnoses with suggested fixes — so you spend less time reading raw logs and more time fixing problems.

How it works

When a webhook delivery fails, FirmHook sends the HTTP status code, response body, and request context to the AI Error Explainer. Within seconds, a natural-language explanation appears alongside the raw response in the event timeline.

Raw response:   500 Internal Server Error

AI explanation: Your endpoint likely timed out after 5 seconds.
                Commonly caused by slow database queries or
                unoptimized server-side processing during peak load.

Suggested fix:  Add index on orders.user_id

The explainer runs automatically on every failed delivery attempt — no configuration required.

Where to find explanations

1. 1Go to Events in the sidebar
2. 2Click any event that has a non-delivered status
3. 3In the event detail page, expand the timeline for any endpoint chain
4. 4Failed delivery attempts show the raw response alongside the AI explanation

The AI explanation is displayed in a highlighted block beneath the raw HTTP response for each failed attempt.

What the AI explains

The AI Error Explainer is trained on common webhook failure patterns and can identify causes including:

• Timeout failures — endpoint took too long to respond; suggests query optimization or async processing
• Authentication errors — 401/403 responses; suggests checking API keys, HMAC signatures, or IP allowlists
• Bad payload errors — 400/422 responses; identifies missing or malformed fields in the request body
• Server errors — 500/502/503; suggests checking server logs, database connections, or downstream dependencies
• Rate limiting — 429 responses; recommends reducing delivery rate or handling retry-after headers

Caching

Repeated failures with the same error signature return the cached explanation instantly. This keeps response times fast when the same endpoint consistently fails with the same error.

Dev Mode

AI explanations are available in local dev mode too. When using firmhook start, any failed delivery to your local server shows an explanation in both the CLI output and the dashboard event timeline.

What's next?

• Understanding Retries — how FirmHook handles delivery failures automatically
• Production Deployment — configure alerts so you're notified when explanations appear