Limits and errors

A refusal is a tool result that says why Hookspot did not run the call and what to do next. Your agent reads it and tells you, so you rarely see one yourself.

How it works

A refusal holds one JSON object. error names the refusal and message says what happened and what to do next. Some refusals add a field, such as resets_at:

{
  "error": "locked",
  "message": "This project's organization used its monthly deliveries, so its projects are locked until resets_at. Its owners and admins can unlock them on Billing (billing_url). Meanwhile webhooks are still received and delivered up to the plan's hard limit, and `hookspot listen` keeps forwarding them.",
  "resets_at": "2026-12-01T00:00:00.000Z",
  "billing_url": "https://<hookspot-host>/documentation-demo/settings/billing"
}

Times are in UTC. billing_url opens the organization’s Settings › Billing.

Tool call limit

Each user can make 120 tool calls a minute, shared by all their authorized apps. Refused calls count too. Past the limit, Hookspot answers rate_limited, and retry_after gives the seconds to wait.

Locks and limits

Your organization’s plan limits apply to agents as they do in the dashboard. Plans and limits explains each limit.

Error	When	Fields
suspended	The organization is suspended. Every project tool is refused, reads included.
locked	A Free organization went over its monthly limit. Every project tool is refused, reads included.	resets_at, billing_url
monthly_delivery_limit_reached	The organization reached its hard limit, so retry_request, replay_request and send_test_request are refused.	resets_at, and billing_url on Free
daily_data_limit_reached	A replay_request would take the organization past its daily data limit.	resets_at, and billing_url on Free

At the hard limit on Pro, no plan lifts the limit. Contact support at [email protected].

Organization tools, such as list_members and get_billing, stay open while the organization is suspended or locked.

The notice

While Hookspot turns an organization’s webhooks away, its project tools’ results carry a notice, whether the call succeeded or Hookspot refused it. That happens at the hard limit and at the daily data limit.

Field	Value
code	monthly_delivery_limit_reached or daily_data_limit_reached, the hard limit’s when both apply
message	What happened, for the agent to tell you
resets_at	When that limit resets: the 1st of next month, or midnight

Webhooks that arrive meanwhile are not stored. The agent can still read what Hookspot stored before.

Other errors

Error	When
read_only	You approved the app as Read-only, and the tool makes changes or gives a dashboard link.
forbidden	Your role can’t do this. The message names the roles that can.
not_found	The UID is unknown, or belongs to an organization you aren’t a member of.
validation_failed	An argument is invalid. fields lists each one with what is wrong.
unknown_tool, unknown_argument	The server has no such tool or argument. The agent’s tool list may be newer than the server, so retry in a minute. A name the agent made up gets the same answer.
tool_retired	Hookspot no longer serves the tool. The message names the tool to use instead.
internal_error	Hookspot failed to answer. Try again. After a write, read the record first, as the write may have taken effect.

Some tools add refusals of their own, such as stale when a record changed since the agent read it. Each message says what to do next.