Docs

Troubleshooting

Quick fixes for common issues with TextForge webhooks, API, MCP connections, and drafts.

Webhooks

Webhook was auto-disabled

Symptom: Your webhook shows "Disabled" on the settings page with a failure count of 10+.

Cause: TextForge disables webhooks after 10 consecutive delivery failures to stop hammering a broken endpoint.

Fix:

  1. Check the delivery log on the webhook settings page for the error details
  2. Fix the underlying issue (endpoint down, URL changed, firewall blocking, etc.)
  3. Re-enable the webhook
  4. Click "Send Test" to verify it works

Signature verification fails

Symptom: Your endpoint receives webhook deliveries but your signature check rejects them.

Common causes:

  • Wrong signed payload format. The signed payload is {timestamp}.{raw_json_body} — the t value from the header, a period, then the raw request body. Make sure you're using the raw body bytes, not a parsed-and-re-serialized version.
  • Wrong secret. Double-check you're using the webhook signing secret (starts with whsec_), not your API token.
  • Body was modified. Some web frameworks parse the JSON body and re-serialize it, which changes whitespace or field order. You need the exact bytes that arrived over the wire.

See Verifying webhook signatures for code examples.

Webhook deliveries time out

Symptom: Deliveries show "timeout" errors in the delivery log.

Cause: Your endpoint takes more than 10 seconds to respond.

Fix: Return a 200 response immediately and process the event asynchronously. TextForge only cares about the HTTP status code, not how long you take to act on the data.

Not receiving certain events

Symptom: You get some webhook events but not others.

Fix: Check which events are selected on your webhook configuration. Go to Settings > Webhooks, click the webhook, and verify all the event checkboxes you need are checked.

API

401 Unauthorized

Symptom: All API calls return 401 Unauthorized.

Common causes:

  • Missing Bearer prefix. The header should be Authorization: Bearer YOUR_TOKEN, not just Authorization: YOUR_TOKEN.
  • Token was revoked. Check Settings > API Tokens to see if the token still exists.
  • Token expired. If you rotated tokens, make sure you're using the new one.

403 Forbidden

Symptom: API calls return 403 Forbidden even though the token works for other endpoints.

Cause: The token doesn't have the required permission for that operation. Each endpoint requires a specific permission scope (e.g., drafts:create, threads:read).

Fix: Check the token's permissions on the API Tokens page. Create a new token with the permissions you need, or edit the existing one.

Rate limiting (429)

Symptom: API calls return 429 Too Many Requests.

Fix: Back off and retry. TextForge rate limits are per-token. If you're hitting limits, space out your requests or batch operations where possible.

MCP connections

OAuth flow doesn't complete

Symptom: The OAuth authorization flow opens in the browser but never completes, or your tool reports a timeout.

Common causes:

  • Popup blocker. Some browsers block the OAuth popup. Allow popups for textforge.net.
  • Network issue. The callback URL needs to reach your local tool. Check that nothing is blocking localhost connections.
  • Tool version. Make sure your MCP client is up to date. Older versions may have OAuth bugs.

"Unauthorized" errors after connecting

Symptom: MCP tools return "Unauthorized - no API token" errors even though you connected.

For OAuth connections: Try disconnecting and reconnecting. OAuth tokens can expire.

For API key connections: Verify the token is valid at Settings > API Tokens. Make sure the Authorization header is formatted as Bearer YOUR_TOKEN.

Tools not showing up

Symptom: Your MCP client connects but doesn't list any TextForge tools.

Common causes:

  • Wrong URL. The MCP server URL is https://textforge.net/mcp (not /api/v1 or /swagger).
  • Tool filtering. Some MCP clients filter tools by name or capability. Check your client's MCP settings for any filters.

Connection drops frequently

Symptom: The MCP connection works initially but drops after a period of inactivity.

Cause: TextForge uses stateless HTTP mode for MCP. Each request is authenticated independently, so there's no persistent session to "drop." The issue is likely on the client side.

Fix: Check your MCP client's timeout and reconnection settings. For mcp-remote proxies, make sure the process stays running.

Drafts

Can't edit a draft

Symptom: update_draft returns "Failed to update draft" or the UI shows the draft as read-only.

Cause: Only drafts in Draft or PendingApproval status can be edited. Once a draft is Approved, Sent, Rejected, or Expired, it's locked.

Fix: If the draft was rejected, create a new draft with the updated content. If it's pending approval, you can still edit it.

Draft expired before I could review it

Symptom: A draft you intended to review shows as Expired.

Cause: TextForge automatically expires drafts that sit in PendingApproval status too long without action.

Fix: Create a new draft. To avoid expiration, review drafts promptly or set up Slack/webhook notifications so you're alerted when new drafts arrive.

Can't delete a draft

Symptom: delete_draft returns an error about the draft's status.

Cause: You can only delete drafts that won't be sent: Draft, Rejected, Expired, or SendFailed status. Drafts that are PendingApproval, Approved, or Sent can't be deleted.

Fix: If the draft is pending approval, reject it first, then delete it.

Quota exceeded error

Symptom: create_draft returns "Draft creation quota exceeded."

Cause: You've hit the daily draft limit for your plan tier. Solo plans allow 20 drafts per day.

Fix: Wait for the daily reset (shown in the error response's resets_at field) or upgrade your plan at Account > Billing.