Happy Hear Audio

Connector

Errors

Failures happen at three layers, and each one looks different on the wire. Before a tool runs, the HTTP layer refuses with a status code. Once a message reaches the server, bad arguments are a JSON-RPC error. Inside a tool, a refusal or failure is a normal result with isError: true and a message written for the operator to read.

1. HTTP refusals

Nothing has run yet. The body is JSON (or empty) and there is no JSON-RPC envelope.

StatusBodyWhenWhat to do
401{"source":"@supabase/server","code":"MISSING_CREDENTIALS", ...}No Authorization header. The response also carries WWW-Authenticate: Bearer resource_metadata="…/api/mcp/oauth-protected-resource", which is how a client discovers the authorization server.Complete the OAuth flow and send Authorization: Bearer <access token> on every request.
401{"error":"oauth_client_token_required"}The token verified, but it is a browser session token rather than one issued to an OAuth client. The connector serves OAuth client tokens only.Obtain the token through the authorization code flow as a registered client, not by copying a dashboard session.
429{"error":"rate_limited"}More than 60 requests from one operator inside 60 seconds. A Retry-After header gives the seconds to wait.Back off for Retry-After seconds. Batch what you can: one tools/call per question is normal usage and never reaches this.
403(empty)A browser-originated request carried an Origin header that is not on the allow-list. Server-side clients send no Origin and are never affected.Call the server from your back end, or from one of the listed hosts.

The first 401 is the one every client sees once: it is how OAuth discovery starts. Follow the resource_metadata URL in WWW-Authenticate; see Authentication.

2. JSON-RPC errors

The envelope was understood but the request could not be served: an unknown method, or arguments that fail the tool’s input schema. The response has an error object and no result.

json
{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32602,
    "message": "Input validation error: Invalid arguments for tool get_event"
  }
}
  • -32602: invalid params. Compare your arguments against the parameters table on the action’s page, or against tools.json.
  • -32601: method not found. Only initialize, ping, tools/list and tools/call do anything here.
  • -32700: the body was not valid JSON.

3. Tool results with isError

The tool ran and declined or failed. The JSON-RPC response is a success; the result has isError: true and one text item. There is no machine code, by design: the message is what an assistant should say to the operator. Match on the text if you must branch; the table below lists every message a tool can return and where.

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "No event with that id in your account."
      }
    ],
    "isError": true
  }
}
MessageReturned by
Could not read events right now.
Could not read that event right now.
No event with that id in your account.
<the unlock message from the dashboard>
Audio cleaning is not available right now.
Daily limit reached: your AI assistant has already made 30 cleaning requests in the last 24 hours, so nothing was changed. You can do this in your Happy Hear dashboard now, or ask again tomorrow. If this looks wrong, email hello@happyhearaudio.com.
Something went wrong on our side. Try again in a minute.
<a validation message>
Daily limit reached: your AI assistant has already made 10 new events in the last 24 hours, so nothing was changed. You can do this in your Happy Hear dashboard now, or ask again tomorrow. If this looks wrong, email hello@happyhearaudio.com.
Provide event_name, event_date, or both
Daily limit reached: your AI assistant has already made 50 event edits in the last 24 hours, so nothing was changed. You can do this in your Happy Hear dashboard now, or ask again tomorrow. If this looks wrong, email hello@happyhearaudio.com.
Could not read the messages on that event right now.
Could not read message states right now.
Could not read your plan right now.

Messages in angle brackets are passed through from the dashboard’s own validation and vary with the input. Everything else is exact text.

What is safe to retry

  • Every read action, always.
  • start_cleaning and update_event: idempotent, safe to retry after a 429 or a “try again” message.
  • create_event: not idempotent. On a “try again” message nothing was created, so one retry is fine; after a 429 or a timeout, call search_events by name first.
  • A daily-limit message: do not retry today. Nothing the client does lifts the cap.
NextChangelog