Troubleshooting integrations

If your integration is not working, the HTTP status code is the first thing to look at. They each mean a specific thing.

401 Unauthorized

The API rejected your authentication. Three flavours:

• missing_authorization: you did not send the Authorization header at all. Add Authorization: Bearer gw_live_....
• invalid_token_format: the header is there but the value is not a valid token shape. Make sure you have Bearer (with the space) followed by the full gw_live_ token and nothing else.
• invalid_token: the token does not match any record. Mostly: you copied it wrong, or the key has been revoked. Mint a new one at Settings → Developer API.
• token_revoked: the key existed but has been explicitly revoked. Mint a new one.

402 Payment Required

The subscription on every Circle the key would let you touch has lapsed. subscription_required. Resubscribe at Billing. The same key works again immediately after, no need to update your integration.

403 Forbidden

You are authenticated and paying, but cannot access this specific resource. Two flavours:

• no_coordinator_access: the key owner is no longer a Coordinator of any Circle. Have a current Coordinator promote them, or use a key from a Coordinator account.
• circle_forbidden: the URL specifies a Circle the key owner does not Coordinate. Check the circle_id in the URL; use GET /api/v1/circles to list the ones you can touch.

404 Not Found

The URL does not exist. Check for typos. Common gotchas:

• The base URL is https://getwello.co.uk/api/v1, not /api or /v1 on its own.
• Path parameters are inside curly braces in the docs; replace them with real IDs (no braces in the actual URL).

400 Bad Request

Your request was malformed. Body might be invalid JSON, or a required field is missing, or a query param is the wrong type. The response body has a message field explaining which.

500 Internal Server Error

Our problem. Either we deployed a bug, or the database hiccuped. Try once more. If it keeps happening, email us with a timestamp and the request URL, we will look.

Webhook receiver returns errors but I cannot tell what

Open Settings → Developer API. Each webhook subscription shows its last success and last failure with a brief reason. If the reason is "HTTP 500" or similar, the problem is on your receiver, not on Getwello. Check your receiver's logs.

Webhook signature verification fails

Common causes:

• You parsed the JSON before computing the HMAC. The signature is over the raw bytes; you need the body string as received.
• You used a different secret. Each subscription has its own. Make sure you are using the one that matches the URL.
• You included the t= and v1= labels in the HMAC string. The signed string is {timestamp}.{body}, not the whole header.
• You compared with ==. Use a constant-time comparison (timingSafeEqual in Node, hmac.compare_digest in Python).

The MCP server connects but Claude says "I don't have access to those tools"

Claude Desktop does not always auto-show MCP tools. Try asking explicitly: "What MCP tools do you have?" If Getwello is listed, ask again with the question rephrased. If not, the MCP server probably failed to start; quit Claude completely (Cmd-Q), reopen, and check the logs.

Still stuck?

Email hello@getwello.co.uk with:

• What you are trying to do (in one sentence).
• The HTTP status code you are seeing (if any).
• The first 12 characters of your API key (the gw_live_xxxx prefix is fine to share; the full key is not).
• A rough timestamp.

We will look in the audit log and tell you what happened.