Errors

AI Workflow MCP errors are intentionally small and machine-readable. Agents should branch on HTTP status for REST and JSON-RPC error.code for MCP.

Authentication

Malformed key:

HTTP/2 401
cache-control: no-store

{
  "error": "invalid API key",
  "hint": "Use Authorization: Bearer ak_..."
}

Unknown, revoked, or deleted key:

{
  "error": "invalid API key"
}

Expired key:

{
  "error": "expired API key"
}

Recovery:

1. Confirm the key starts with ak_.
2. Confirm the request uses Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}.
3. Create a new key from https://aiworkflowmcp.com/en/account/api-keys/.
4. Revoke old keys that may have leaked.

REST Validation

Missing search query:

{
  "error": "q is required"
}

Invalid type:

{
  "allowed_types": [
    "DOC",
    "MCP_SERVER",
    "MODEL",
    "SKILL",
    "TOOL",
    "TUTORIAL"
  ],
  "error": "invalid type"
}

Unknown detail id:

{
  "error": "model not found"
}

Equivalent detail errors exist for tools, skills, MCP servers, and frameworks.

JSON-RPC Errors

Invalid JSON:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "invalid JSON"
  }
}

Batch requests:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "batch requests are not supported"
  }
}

Unknown method:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found: example"
  }
}

Tool execution failure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "model_id is required"
  }
}

Recovery:

• Call tools/list and validate the tool name.
• Send an object in params.arguments.
• Use required argument names exactly as documented.
• Use concise English inputs for search tools.

Rate Limit

Rate-limited calls return:

HTTP/2 429
retry-after: 60

{
  "error": "rate limit exceeded",
  "limit_per_minute": 120,
  "retry_after_seconds": 60
}

Authenticated keys use a higher per-minute limit. Back off for at least the retry-after value before retrying.

Freshness

When fresh_only=true is set, search and tool paths can reject stale facts instead of returning older data. If a freshness-sensitive path fails:

1. Check https://mcp.aiworkflowmcp.com/health.
2. Check https://api.aiworkflowmcp.com/v1/sources/status.
3. Retry after source refresh if stale_entities, source_errors, or source_refresh_due are non-zero.
4. Drop fresh_only=true only for exploratory discovery where stale data is acceptable.

Status Handling

• 200: request succeeded.
• 202: accepted MCP signal or notification with no response body.
• 400: invalid REST query or JSON-RPC request.
• 401: API key problem.
• 404: unknown detail resource or method.
• 429: per-minute rate limit.
• 500: unexpected service failure.