Help: For agent builders

Handling responses

This page is for people who build agents. It lists everything funwatcher can answer and what a well-behaved agent does next. The rule behind all of it: act only on an answer that says proceed, and treat everything else as "do not act".

Every status

The status field of an answer holds one of these values, written as shown in the first column.

StatusWhat the agent should doWhat can follow
pending No answer yet. Do not act. Wait on the request, or tell the user and ask whether to keep waiting. approved, denied, cancelled, expired
held No answer yet. Do not act. The action is released when the hold ends unless a person cancels it. Wait on the request. cancelled, released
approved Proceed. If edited_payload is present, act with exactly that payload. Then report the result. executed, failed
denied Do not act. Tell the user and stop. Nothing. Final.
cancelled Do not act. Tell the user and stop. Nothing. Final.
expired Do not act. Nobody decided in time. Tell the user. To ask again, submit a new request with a new idempotency key. Nothing. Final.
released Proceed. Then report the result. executed, failed
executed Nothing. This is the result you reported. Nothing. Final.
failed Nothing. This is the result you reported. Nothing. Final.
auto_allowed Proceed. Then report the result. executed, failed
prohibited Do not act. The account's rules forbid this action. Tell the user and stop. Asking again gives the same answer. Nothing. Final.

A submission is answered at once with pending, held, auto_allowed or prohibited. The other statuses appear when you read or wait on the request later.

timed_out

The wait route adds timed_out to its answer.

One wait call lasts at most 30 seconds, so waiting for a person means calling it in a loop. Stop looping when the status is anything other than pending or held.

edited_payload

Reporting the result

  1. After an attempt on an approved, released or auto_allowed request, call the report route once.
  2. Send outcome as executed if the action was carried out, or failed if it was attempted and did not succeed.
  3. Add external_ref (a transaction id, message id or address) and detail if you have them.

A report on a request in any other status is refused with HTTP 409. A second report on the same request is refused the same way. The report is recorded as the agent's statement. funwatcher cannot confirm it.

Maintenance (HTTP 503)

While maintenance mode is on, every route under /api/v1 answers HTTP 503 with a Retry-After header of 120 seconds and the body {"error": "…", "maintenance": true}, where the error is a sentence for the user.

Other answers

CodeMeaningWhat the agent should do
401The key is missing, wrong or revoked.Stop and tell the user. Retrying with the same key does not help.
404No such request in this key's account, or the agent id on the webhook route is not this key's agent.Check the id. Do not act.
409The request's status does not allow the call, for example cancelling a decided request or reporting on a pending one.Read the request's status and follow the table above.
413The payload is larger than 65536 bytes.Send a smaller payload. Do not act until a submission succeeds.
422The body is not valid. The answer lists each problem under details.Fix the body and submit again.
429 with Retry-AfterMore than 120 calls in 60 seconds with one key.Wait for the time in the header.
429 without Retry-AfterThe agent already has 25 requests that are pending or held.Wait for decisions, or cancel requests that are no longer needed.

Withdrawing a request

If the action is no longer needed while its status is pending or held, call the cancel route. The status becomes cancelled. A request in any other status cannot be cancelled.

For the routes and limits, see API overview. For the same answers through MCP, see MCP tools.

Previous:
Next:

All help pages

Inbox

Rules

Teams

Ledger

Billing

Account and security

For agent builders

Troubleshooting