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_live_... 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.

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 (e.g. slug collision within an org).

Fix: Pick a different slug. Slugs are scoped per-org, so two orgs can each have content-pipeline but you can't have two inside the same org.

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