Errors

When something goes wrong with a Zoop API call, the error comes from one of two places: the auth layer checks your credentials before anything runs, and the tool layer runs your requested action after auth passes. Knowing which layer failed tells you exactly what to fix.

Auth-layer errors

Auth errors happen before Zoop runs your tool — your credentials didn't check out. The response uses a JSON-RPC error envelope (a standard response wrapper with a jsonrpc, id, and error field). Because the request never reached the tool, id is always null.

Error envelope shape

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Unauthorized"
  }
}

When extra context is available — for example, which scopes (permissions) your token is missing — it appears in an error.data field:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32002,
    "message": "Insufficient scope",
    "data": {
      "required": ["write:jobs"]
    }
  }
}

Auth error reference

invalid_token reasons

When the error is invalid_token, Zoop records an internal reason code. This code does not appear in the HTTP response — you won't see it in your app. It does appear in server logs and audit events, so it's useful when working with Zoop support to diagnose a persistent failure. Common values:

401: missing or invalid token

Check that your Authorization header is present and correctly formatted:

Authorization: Bearer zoop_uk_<rest of key>

The full key — including the zoop_uk_ or zoop_tk_ prefix — must be present. If you are using an OAuth access token, make sure the JWT was issued by the correct authorization server and has not been modified in transit.

401: revoked or expired

A revoked key cannot be restored. Go to Settings → API & MCP and create a new API key. For an expired OAuth access token, use your refresh token to get a new access token.

See API keys and OAuth for details.

403: insufficient scope

Your token is valid but is missing a permission (scope) that the tool requires. The error.data.required array lists exactly which scopes you need to add:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32002,
    "message": "Insufficient scope",
    "data": {
      "required": ["write:jobs", "read:customers"]
    }
  }
}

You cannot add scopes to an existing API key. Revoke the current key, then create a new one with the required scopes selected. For OAuth tokens, re-authorize the user with the additional scopes. See Scopes for the full scope catalog.

403: wrong tenant

Your API key belongs to a different Zoop account (tenant) than the one you're calling. Double-check that you're using the right key for this account.

429: rate limited

You've sent too many requests too quickly. Wait the number of seconds given in the Retry-After response header, then try again:

# The Retry-After header value is in seconds
Retry-After: 30

See Rate limits for per-credential and per-tenant limits.

WWW-Authenticate header

On 401 responses, Zoop includes a WWW-Authenticate header. OAuth 2.0 clients can follow the URL in that header to auto-discover the authorization server, supported scopes, and token endpoint:

WWW-Authenticate: Bearer realm="zoop", resource_metadata="https://app.zoop.example/.well-known/oauth-protected-resource"

If you're using a simple API key, you can ignore this header.

Tool-layer errors

Once your credentials pass, Zoop runs the tool you called. If the tool itself fails, the HTTP status is still 200 — but the response body signals the failure with isError: true and a plain-English message in content[0].text.

Tool error envelope shape

Tool errors appear inside the normal tools/call result, not as a top-level JSON-RPC error object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Resource not found."
      }
    ],
    "isError": true
  }
}

Always check isError in your code — a 200 status does not mean the tool succeeded.

Tool error kinds

invalid_input detail

The invalid_input response always contains the same fixed message, regardless of which field is wrong:

{
  "type": "text",
  "text": "Invalid input. Check the schema."
}

Zoop does not tell you which field failed. When you see this error, go back to the tool's parameter definitions and check every required field, its type, and any allowed values — the response won't name the offending field for you.

conflict detail

The conflict message is a plain English sentence that describes what already exists. Read it directly:

{
  "type": "text",
  "text": "Already exists"
}

Quick-reference: error layers

Related pages