Troubleshooting integrations

Problem	Resolution
MCP initializes but execution returns 401	Set `SOCQ_API_KEY` or configure a bearer token. See Integration authentication.
Typed tool is missing	Check the `platforms` or `tools` filter, then restart the client. See Choose MCP tools.
MCP call returns a task ID	This is expected. Continue with `socq_get_task`; see Tasks and results.
Polling timed out	Resume with the same task ID instead of resubmitting.
400 validation error	Run `socq describe PLATFORM/RESOURCE` or inspect the endpoint schema and remove unsupported fields.
403	Check API-key status and its IP allowlist.
409	Use a new idempotency key, or retry the original request with unchanged input.
402 or 429	Check account credits and API-key limits. Follow the retry guidance in API errors.
CLI dynamic flag is rejected	Refresh the live Capability Catalog and use the field spelling from its JSON Schema.

For protocol-level failures, verify that the proxy preserves Authorization, Accept, Content-Type, and MCP-Protocol-Version, and that it routes the exact /mcp path without appending a second /mcp segment.