> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swoop.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understand error responses and common error scenarios from the Swoop MCP server

## Error format

All tool errors are returned in a consistent MCP format:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Error message describing what went wrong"
    }
  ],
  "isError": true
}
```

The `isError: true` flag signals to your MCP client that the tool call did not complete successfully. The `text` field contains a human-readable description of the error.

## Common error scenarios

<AccordionGroup>
  <Accordion title="401 Unauthorized — Missing or invalid token">
    The request does not include a valid Bearer token, or the token has expired or been revoked.

    The server returns a `401` response with a `WWW-Authenticate` header similar to:

    ```
    WWW-Authenticate: Bearer error="invalid_token", error_description="No authorization provided", resource_metadata="https://swoop.it/.well-known/oauth-protected-resource"
    ```

    **Resolution:**

    * Verify your `Authorization` header format: `Bearer <token>`
    * For API keys, ensure the key starts with `ak_` and has not been revoked
    * For OAuth, re-authenticate by completing the OAuth flow again
    * Use the `resource_metadata` URI to discover the authorization server and obtain a new token
  </Accordion>

  <Accordion title="404 Not Found — Invalid URL">
    The request was sent to an incorrect URL.

    **Resolution:**

    * Verify you are using the correct URL: `https://swoop.it/api/mcp`
    * Ensure there are no trailing slashes or extra path segments
  </Accordion>

  <Accordion title="Tool execution timeout">
    Presentation generation can take 30–60 seconds. If the connection closes before the operation completes, the tool call will fail.

    **Resolution:**

    * Ensure your MCP client supports long-running operations (at least 120 seconds)
    * Check that any proxy or load balancer between you and the server has a timeout of at least 120 seconds
    * The server sends heartbeat notifications every 10 seconds — ensure your transport layer processes these to keep the connection alive
    * Try a simpler prompt to verify connectivity
  </Accordion>

  <Accordion title="CORS errors in browser-based clients">
    The Swoop MCP server allows cross-origin requests from all origins (`Access-Control-Allow-Origin: *`).

    **Resolution:**

    * Ensure you are using the correct endpoint URL
    * Check that browser extensions are not modifying request headers
    * Try in a private/incognito browser window
  </Accordion>

  <Accordion title="Network connectivity issues">
    Unable to establish a connection to the server.

    **Resolution:**

    * Check that your network allows outbound HTTPS connections
    * If behind a corporate firewall or VPN, ensure `swoop.it` is not blocked
    * Test connectivity with a simple `curl` request:

    ```bash theme={null}
    curl -I https://swoop.it/api/mcp
    ```
  </Accordion>
</AccordionGroup>