API and MCP Troubleshooting

Start by recording the UTC time, operation, status, sanitized response, client version, and request/delivery ID. Never record the API key.

Fast diagnostic sequence

Confirm the documentation URL is on docs.workestra.app.
Confirm API calls use https://platform.workestra.app directly.
Verify the bearer header is exactly Authorization: Bearer wks_....
For MCP, call /api/mcp/session.
Retrieve the live tool/schema list.
Reproduce with the smallest read-only request.
Branch on the HTTP status below.

HTTP errors

400 or 422: invalid request

Compare the request against the dedicated endpoint guide or live MCP schema.
Remove fields not explicitly accepted; many REST handlers use strict schemas.
Check UUIDs, ISO timestamps, enum casing, empty strings, and required kind fields.
Confirm Content-Type: application/json and valid JSON.
Do not assume the generic OpenAPI placeholder accepts arbitrary properties.

401: authentication failed

Confirm the key begins with wks_.
Confirm the header contains one Bearer prefix and no quotes.
Use platform.workestra.app directly; cross-host redirects may remove the header.
Check expiry, revocation, workspace state, and accidental whitespace.
Ensure the secret was added to the MCP/client process, not only the interactive shell.

Test:

curl -i "https://platform.workestra.app/api/mcp/session" \
  -H "Authorization: Bearer $WORKESTRA_API_KEY"

403: permission denied

The credential is valid but lacks the route scope or MCP permission.
Inspect permissions.granted, allowedToolNames, and denied tool metadata.
Check whether --read-only or --features filtered the local MCP registry.
Explain the missing permission before asking an Admin to replace the key.

404: route, tool, or resource not found

Verify the full path and HTTP method.
Use a supported route from the status page.
For MCP, retrieve allowedToolNames; unknown tools and denied tools differ.
Verify the resource belongs to the API key's workspace.
Remember that www.workestra.app/docs/api is not the documentation host; use docs.workestra.app/docs/api.

409: conflict

Read the current resource before retrying. Typical causes include duplicate identifiers, invalid state transitions, concurrent updates, or already-consumed capabilities.

429: rate or quota limit

Honor Retry-After.
Add exponential backoff with jitter.
Keep a maximum retry count and total elapsed-time budget.
Reduce polling, cache reads, and use webhooks where their latency is acceptable.
A monthly CRM quota and per-minute route/MCP limits are different controls.

500-504: server or upstream failure

Retry only reads or known-idempotent writes.
Use a bounded retry budget.
Preserve the sanitized response and request ID.
Check Known Contract Limitations before escalating.

MCP-specific failures

The client shows no Workestra tools

Confirm the MCP process starts successfully.
Pin workestra-mcp@2.0.4 for a reproducible test.
Confirm the API key is available to that process.
Call /api/mcp/session directly.
Remove --features temporarily.
Check whether --read-only is intentionally set.
Restart or reconnect the MCP server in the client.

A documented tool is missing

The deployed registry and key policy are authoritative. Retrieve:

GET /api/mcp/tools/list?includeDenied=true&includeSchemas=true

Check whether the tool is denied, filtered by feature, blocked by an agent-trial policy, or absent from the deployed tool version.

Tool arguments are rejected

Use the schema returned by /api/mcp/tools/list. Do not translate REST field names into MCP arguments or copy parameters from another tool.

A write ran without a Workestra confirmation card

That is expected for external MCP clients. Workestra's confirmation card belongs to the in-app AI surface. External agents must explain the write and obtain any required user approval before calling the tool.

REST-specific failures

OpenAPI-generated client accepts fields that runtime rejects

OpenAPI publication is temporarily paused. Do not use a previously cached specification. Use the endpoint guide or live MCP schema until the sanitized download is linked from the OpenAPI status page.

Response envelope differs

Most v1 routes return { data, pagination? }, but several older create handlers return an object directly. Branch on the endpoint guide and actual status/body rather than assuming every route is identical.

Issues return the wrong resource type

Set kind=task or kind=ticket explicitly. An omitted kind currently defaults to project tasks. Do not use /api/v1/issues/{id} DELETE for support tickets.

Webhook failures

Signature mismatch

Use the exact raw JSON bytes.
Sign <timestamp-seconds>.<raw-body>, not the body alone.
Use the secret for that subscription.
Compare the full sha256=<hex> value in constant time.

OpenAPI publication is temporarily paused pending the sanitized application release.
Webhook delivery can take up to 24 hours on the current service tier.
Some webhook event names retain compatibility aliases; use the event name shown in delivery history and test payloads.
The Zapier integration is not currently available for production use.
/api/v1/issues DELETE supports project tasks, not support tickets.

Contact support

Email support@workestra.app. Include:

Workspace ID:
UTC timestamp:
REST method/path or MCP tool:
HTTP status:
Request/delivery ID:
Client and version:
Expected behavior:
Actual behavior:
Sanitized request:
Sanitized response:
Reproduction steps:

Never include an API key, session token, approval token, capability token, private attachment URL, or unnecessary personal data.