Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Reference

Error codes

Every error Dock can return, anchored by code so agents (and humans) can look up cause + fix deterministically. Every response also carries an x-request-id header; include it when reporting issues.

Error shape

RESTjson
{
  "error": "validation",
  "message": "slug must match ^[a-z0-9-]+$",
  "details": [{ "path": ["slug"], "code": "invalid_string" }],
  "requestId": "req_01HX..."
}
MCP (JSON-RPC)json
{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32015,
    "message": "Free tops out at 3 agents. Pro is $19/mo for 10 agents.",
    "data": {
      "plan": "free",
      "active": 3,
      "cap": 3,
      "upgrade":  { "mcpTool": "upgrade_plan",           "api": "POST /api/billing/upgrade", "plan": "pro" },
      "increase": { "mcpTool": "request_limit_increase", "api": "POST /api/billing/request-limit-increase" }
    }
  }
}

Auth

unauthorizedHTTP 401Unauthorized
When: No credentials, or Bearer token / session cookie invalid.
Fix: Include an Authorization: Bearer dk_... header on every request. Or, if running in a browser session, include the dock-session cookie.
forbiddenHTTP 403Forbidden
When: You're authenticated, but not a member of this workspace / org.
Fix: Ask the workspace owner to invite you (Share · your email) or mint a key scoped to a workspace you already belong to.
elevation_requiredHTTP 401Sudo-mode elevation required
When: The endpoint is gated behind a sudo-mode (sensitive) action — credential change, key mint, org-member removal, workspace delete. You're authenticated, but the calling session hasn't completed an elevation handshake within the 15-minute sliding window.
Fix: Re-authenticate via POST /api/me/elevate with the specific scope the endpoint requires (the 401 body names it under details.requiredScope). The elevation grant is scoped to that single capability and expires 15 minutes after last use; subsequent calls under the same scope reuse the grant. Browser flows redirect to an inline confirm prompt automatically; programmatic callers must surface the elevation step to the user before retrying.
rate_limitHTTP 429Rate limit exceeded
When: Sliding-window limit hit (magic-link, writes, OAuth exchange, invites).
Fix: Back off and honor the Retry-After header. See API · rate limits for the exact per-bucket caps.

Validation + shape

bad_requestHTTP 400Bad request
When: Request malformed in a way Zod's schema validator rejected.
Fix: Check the details[] array on the error for the exact field. Dock uses Zod issues, one per invalid field.
validationHTTP 422Validation failed
When: Body parsed as JSON but failed schema validation.
Fix: Same as above. Example cause: slug not kebab-case, email not a valid RFC5322 address, body too long.
conflictHTTP 409Conflict
When: Resource already exists, or a stateful operation collides with current state. Two common cases: (1) slug collision within an org — creating a workspace whose slug is already taken; (2) unarchive collision — trying to unarchive a workspace whose slug was reclaimed by a new workspace after the archive.
Fix: For slug collisions on create: pick a different slug. Slugs are scoped per-org, so two orgs can each have content-pipelinebut you can't have two inside the same org. For unarchive collisions: rename the blocking workspace first, or rename the archived one as part of the unarchive call.
not_foundHTTP 404Not found
When: Resource doesn't exist or isn't visible to the caller. Non-member slug lookups return 404 rather than 403 to prevent existence enumeration.
Fix: Re-check the slug / id. If you think it should exist, verify you're a member.

Plan caps + billing

payment_requiredHTTP 402Cap hit (agents / workspaces / rows / members)
When: The org hit its plan limit on the resource you're creating. Response body includes the upgrade/increase next-step payload.
Fix: Read details.upgrade for POST /api/billing/upgrade (or the upgrade_plan MCP tool). Past Scale's caps, read details.increase for POST /api/billing/request-limit-increase.

Internal

internalHTTP 500Internal server error
When: Unhandled exception. Captured in Sentry.
Fix: Grab the x-request-id from the response headers and file a ticket via create_support_ticket (MCP) or POST /api/support with kind: "bug". Include that id in the context field.

MCP-only (JSON-RPC error codes)

-32001HTTP 401Unauthorized (MCP)
When: Missing or invalid OAuth access token / API key on /api/mcp. Returned at HTTP status 401 with WWW-Authenticate pointing at /.well-known/oauth-protected-resource.
Fix: Follow the OAuth 2.1 DCR flow, or use a Bearer dk_ key.
-32015HTTP 200Plan cap hit (MCP)
When: Mirror of the REST 402 payment_required error, but in JSON-RPC envelope (HTTP 200 with `error` field).
Fix: Body shape mirrors REST: data.upgrade and data.increase carry next-step endpoints and tools.
-32601HTTP 200Method not found
When: You called a JSON-RPC method Dock doesn't implement, or a tool name that doesn't exist.
Fix: Use tools/list first to enumerate the 13 supported tool names.
-32602HTTP 200Invalid params
When: Tool arguments missing a required field, or wrong type.
Fix: Check the tool schema via tools/list. Every required argument is marked "required": true.
-32603HTTP 200Internal error
When: Something blew up inside the MCP dispatcher. Rare.
Fix: Retry. If it persists, file a support ticket with the request id.

Reporting bugs

If you hit an error that isn't explained above, file a ticket with the x-request-id from the response headers. The fastest path:

curl -X POST https://trydock.ai/api/support \
  -H "Authorization: Bearer dk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "bug",
    "title": "<short summary>",
    "body": "<steps + expected vs actual>",
    "context": { "requestId": "req_01HX..." }
  }'

Related: REST API reference · MCP reference · Support

Frequently asked questions

What does Dock's 401 Unauthorized error mean?
Your `Authorization: Bearer dk_...` header is missing, malformed, or the key is revoked / expired. Common typo: missing space after `Bearer`, or the `dk_` prefix dropped. Check Settings → API keys to confirm the key is still listed; rotate if in doubt.
What does Dock's 403 Forbidden error mean?
Your auth is valid (we know who you are) but the principal lacks permission for this resource. Check the workspace member list; the principal may be a viewer trying to write, or scoped to a different workspace, or not a member at all.
What does Dock's 402 Payment Required error mean?
You hit a plan cap (agents, members, workspaces, rows, API calls, webhooks). The payload includes `details.upgrade.message` (what to surface to the user) and `details.upgrade.mcpTool` (what the agent should call). Same error shape on REST and MCP (JSON-RPC code -32015). Learn more →
What does Dock's 400 ambiguous_slug error mean?
Your call referred to a workspace by bare slug, but the principal has access to two workspaces with the same slug across different orgs. The hint includes both canonical paths (e.g. `/vector-apps/content-pipeline` vs `/govind-s-org/content-pipeline`); use the org-prefixed form.
What does Dock's 409 Conflict error mean?
Resource collision. Most common: trying to add a column with a key that already exists, or rename a workspace slug to one already in use within the org. The error message names the conflicting field; pick a different value.
What does Dock's 429 Too Many Requests error mean?
You hit a per-principal burst rate-limit (designed to prevent any one agent from monopolizing capacity). Back off briefly (the `Retry-After` header gives seconds) and retry. Sustained 429s mean you've grown beyond the burst envelope; consider batching.
What does Dock's 404 Not Found error mean?
Either the resource doesn't exist, or the principal lacks read access (`404 = either-or` is the security default; we don't leak existence). For a workspace 404, check the slug + org; for a row 404, confirm the row id and the workspace.
What does Dock's confirmation_required response mean?
Not an error per se. Dangerous-ops MCP tools (`upgrade_plan`, `downgrade_plan`) return this on the FIRST call: `{ status: 'confirmation_required', confirm_token, message, expires_in }`. Surface to user, get consent, re-call with the token within 60s. Learn more →
How do I report a Dock API error to support?
Include the `x-request-id` from the response headers (Dock returns it on every response). Support can pull the full server-side trace by request id in seconds. Without it, debugging is much slower; always grab it.
Where do I find Dock's full API error reference?
This page enumerates every code Dock returns. The Zod schema validation errors include a path + message; the rate-limit headers + 402 payload `details` block give actionable context. For obscure errors, the `error_description` field on the response is usually the most informative.
Updated