vatverify home
Start free
All errors

webhook_limit_reached

You have reached the maximum of 5 registered webhook endpoints for this API key.

HTTP 400 · Bad Request

Example response

{
  "error": {
    "code": "webhook_limit_reached",
    "message": "Maximum of 5 webhook endpoints per key."
  },
  "meta": {
    "request_id": "a1b2c3d4-...",
    "latency_ms": 0
  }
}

What happened

Each API key can have at most 5 registered webhook endpoints. This limit prevents runaway registration loops. Deletion is the off switch: remove an existing endpoint to free a slot.

How to fix

  1. List your current endpoints with GET /v1/webhooks to see what is registered.
  2. Delete an endpoint you no longer need with DELETE /v1/webhooks/{id}.
  3. Retry your registration request.

Why the limit exists

The 5-endpoint cap is per API key, not per account. The cap protects two failure modes:

  • Registration loops: a buggy deploy script that re-registers the same webhook on every boot will hit the cap quickly. Hitting webhook_limit_reached is the signal to fix the loop, not to lift the cap.
  • Fan-out cost: every webhook event is delivered to every registered endpoint with retries on failure. A larger cap on a low-tier plan would let one customer generate disproportionate outbound traffic.

If your architecture genuinely needs more than 5 endpoints under one key, the typical pattern is to fan out internally from a single webhook receiver to multiple downstream consumers. That keeps the cap for vatverify simple and moves the multiplexing into your own infrastructure where you can scale it.

Edge cases

  • Endpoint with the same URL counts as a separate registration. If you accidentally register the same URL twice, both consume slots. List with GET /v1/webhooks and dedupe.
  • A revoked endpoint still counts until deleted. Disabling an endpoint via the dashboard pauses delivery but does not free the slot. Use DELETE /v1/webhooks/{id} to actually remove it.
  • Test-mode keys have the same cap. Test-mode webhooks are useful for local development but the 5-endpoint cap applies; rotate test endpoints aggressively rather than accumulating them.

Related errors