Errors & troubleshooting

Check both the HTTP status and the response body. Save X-Request-ID when present, the endpoint, time and a redacted description of the request. Do not paste keys, OAuth tokens or customer records into logs or support messages.

Public Query/Search/Events and OData errors use this envelope. For example, a permission failure returns:

{
  "error": {
    "code": "external_access_permission_denied",
    "message": "The API key does not allow this operation."
  }
}

Public validation messages can be intentionally general. Use the authenticated Query/Search/Event Explorer to inspect current fields and valid workroom choices. Their signed-in management responses do not necessarily have the same shape as external responses.

Revoked or inactive keys are rejected with 403, not always 401. A key from another workroom cannot be repointed with X-Workroom-ID; create/use the intended workroom’s credential. The ordinary app login token is not an external API key.

Do not assume a Retry-After header exists. A 422 may mean a space UUID was supplied where a stable crm_space_key was needed. Copy the request scope from Query Explorer. An empty result is not necessarily an error: check the key’s workroom, subspace, filters, archive state and dataset visibility rules.

HTTP 202 only acknowledges queuing. Find the returned event_id in Settings → Developers → Event Activity, in the same workroom as the key. Inspect pending, processing, succeeded, failed or dead_letter, then open the detail view to read the result.

A permanent business validation failure enters dead_letter. Transient/unexpected processing failures are retried up to five times. An owner/admin can replay an eligible failed/dead-letter event after resolving its cause. Do not create a new idempotency key to force another copy of the same business operation.

For Flow+ outgoing HTTP calls, inspect the workflow’s run history and destination response. Check configured authentication, public destination reachability, body mapping and the actual method’s retry behavior. The Events API does not provide an outgoing subscription-delivery log or generic webhook replay endpoint.

If an analytics client repeatedly prompts for credentials, use Basic with a Data Access key as the password, and replace cached credentials after rotation. Integration keys cannot authenticate OData. Start from the service root and inspect metadata before adding filters. Power BI setup and refresh notes distinguish desktop import from online refresh.

Use https://mcp.workroomly.com/mcp with a client that supports Streamable HTTP and OAuth. Allow the browser sign-in window to open, then sign in to Workroomly and authorize the connection. Use the remote server URL in your client’s configuration; an API-key header cannot replace OAuth consent.

If a tool is missing, check the connection’s read/write scopes, current membership and chosen product/subspaces. Some deployments use searched discovery. Reconnect to change granted permissions; do not substitute another workroom ID to bypass the grant.

Tool execution errors contain code, message, request_id, retryable and details. For permission_denied, inspect the grant and current native role. For validation_failed, inspect the arguments and discovered schema. invalid_backend_response means the service could not validate a backend result; retain the request ID for support. The MCP framework may report malformed tool input separately.

For a revision conflict, retrieve the current record and review changes before issuing a new mutation. After a network timeout, retain the original idempotency key and arguments. A pending approval is a business result, not a failed connection. Consult MCP results and safety guidance before retrying writes.