Error codes

Proxy errors

These are returned to the webhook sender (Stripe, Paddle, etc.) by the proxy endpoint.

project_not_found — 404

{ "error": "project_not_found", "project": "acme/payments" }

Cause: The org slug or project slug in the URL doesn’t match any registered project.

Fix: Check the endpoint URL configured in your webhook provider. The format is https://hookman.dev/w/{org}/{project}.

---

no_route_resolved — 422

{
  "error": "no_route_resolved",
  "hint": "Set an active deployment or include a routing key",
  "routingMethod": "header",
  "keyFound": "unknown-branch"
}

Cause: One of two things:

• No routing strategy matched and there is no active deployment set
• A routing key was found but didn’t match any registered deployment label

Fix:

• If keyFound is present, a routing key was extracted but no deployment has that label. Register a deployment with that label, or check for a typo.
• If keyFound is absent, no key was found at all and there is no active deployment. Set an active deployment in your dashboard or configure a routing strategy.

---

quota_exceeded — 429

{
  "error": "quota_exceeded",
  "used": 1000,
  "limit": 1000,
  "plan": "free"
}

Cause: Your org has exceeded its monthly webhook quota.

Fix: Upgrade your plan, or wait until the quota resets at the start of the next billing period (the 1st of each month). Note: Stripe and similar services will retry on 429 — check that this isn’t causing a retry storm.

---

rate_limited — 429

{ "error": "rate_limited", "retryAfter": 60 }

Cause: Too many requests per minute from a single IP to a single project.

Fix: This is unusual in normal webhook delivery (senders don’t typically send hundreds per minute). If you’re seeing this during testing, space out your test requests.

---

Management API errors

These are returned by api.hookman.dev endpoints.

unauthorized — 401

{ "error": "unauthorized" }

Cause: No valid session cookie or API key was provided, or the key has been revoked.

Fix: Include a valid Authorization: Bearer hm_live_xxx header, or re-authenticate your session.

---

forbidden — 403

{ "error": "forbidden", "reason": "insufficient_role" }

Cause: Your API key or session has insufficient permissions for this action. For example, a member role attempting to delete an org.

Fix: Check the role permissions table. Use an API key or account with the required role.

---

not_found — 404

{ "error": "not_found", "resource": "deployment" }

Cause: The resource (org, project, deployment, etc.) doesn’t exist, or you don’t have access to it.

---

validation_error — 422

{
  "error": "validation_error",
  "fields": {
    "targetUrl": "Must be a valid HTTPS URL",
    "label": "Must be 1–100 characters"
  }
}

Cause: The request body failed validation.

Fix: Check the fields object for per-field error messages.

---

plan_limit_reached — 422

{
  "error": "plan_limit_reached",
  "resource": "projects",
  "limit": 1,
  "current": 1,
  "upgradeUrl": "https://hookman.dev/pricing"
}

Cause: You’ve hit a plan limit — for example, trying to create a second project on the Free tier.

Fix: Upgrade your plan, or remove an existing resource to free up a slot.

---

Upstream errors (logged, not returned)

These are not returned to the webhook sender — Hookman returns 200 to prevent retry storms. They appear in the webhook log.

Log error	Meaning
upstream_timeout	The target URL did not respond within 10 seconds.
upstream_connection_refused	Could not connect to the target URL.
upstream_5xx	The target responded with a 5xx status.
upstream_invalid_url	The registered target URL is not reachable (bad hostname, etc.).
max_retries_exceeded	Retry queue exhausted all attempts (Pro/Team only).

For all upstream errors, the webhook payload is still stored for replay if your plan supports it.